# molecule-cli Go CLI for the Molecule AI agent platform. Wraps the platform's workspace runtime and control plane APIs, providing a unified command-line interface for managing agents, workspaces, and deployments. **Users:** Platform operators and developers integrating with the Molecule AI platform. **Repo state (2026-04-16):** Thin/stub. Go module is initialized; core CLI commands are not yet implemented. CI (Go binary release via GoReleaser + GitHub Actions) is wired up. --- ## 1. Project Overview This CLI is the primary user-facing tool for interacting with the Molecule AI platform. Typical responsibilities: - Workspace lifecycle management (create, destroy, inspect) - Control plane interaction (agents, deployments, config) - Local development proxy / dev mode against the workspace runtime - Configuration management (env vars, config files, workspace templates) ## 2. Build, Test, and Local Run ```bash # Build the binary to ./bin/molecule go build -o bin/molecule ./cmd/molecule # Run the test suite (24 integration tests) go test ./... # Run the CLI ./bin/molecule --help ``` ## 3. Go Module Conventions **Module path:** `github.com/Molecule-AI/molecule-cli` (from `go.mod`) **Dependency management:** - Use `go mod tidy` after adding or removing dependencies. - Pin transitive dependencies if platform compatibility is a concern; document why in a comment. - Do not commit generated lock files beyond `go.sum`. `go.sum` is the lock. - Before upgrading a major dependency (especially the platform SDK), check whether the platform enforces API compatibility constraints (`docs/development/constraints-and-rules.md`). **go.sum hygiene:** Run `go mod tidy` and `go mod verify` in CI. A dirty `go.sum` (extra entries, missing checksums) is a CI failure. ## 4. Release Process Releases are fully automated via GoReleaser + GitHub Actions. You do not need to run GoReleaser locally. **To cut a release:** ```bash # 1. Pull and ensure you're on main with a clean history git checkout main && git pull # 2. Tag with a semantic v prefix; push the tag git tag v0.1.0 git push origin v0.1.0 ``` The GitHub Actions workflow (`.github/workflows/release.yml`) triggers on tags matching `v*`. GoReleaser builds the binary for the configured targets and creates a GitHub Release automatically. **Rules:** - Tags must match `v*` (e.g., `v0.1.0`, not `0.1.0`). - Do not push release tags from branches; always from a clean main. - If the release build fails, fix forward: do not delete remote tags. Create a corrected tag (e.g., `v0.1.1`) and push it. - Changelog is generated by GoReleaser from conventional commits. Use conventional commit messages on merged PRs. ## 5. Platform Integration Notes The CLI will interact with the Molecule AI platform via two interfaces: **Control plane API:** REST/HTTP endpoints for agent management, workspace lifecycle, and deployment config. Endpoint base URL is configured via environment variable. **Workspace runtime:** The local or hosted runtime that executes agent workloads. The CLI proxies or delegates to this runtime in dev mode. **Required environment variables:** | Variable | Description | Required | |---|---|---| | `MOLECULE_API_URL` | Control plane API base URL | Yes | | `MOLECULE_RUNTIME_URL` | Workspace runtime URL | For dev/proxy mode | | `MOLECULE_API_TOKEN` | API authentication token | Not yet; MVP has no auth per platform rules | > **Note:** Per platform constraints (`docs/development/constraints-and-rules.md`), this is an MVP repo with no auth. The CLI should not emit or accept bearer tokens unless the platform constraints doc is updated. **Platform docs to read before touching auth or secrets:** - `docs/development/constraints-and-rules.md` - `docs/runbooks/saas-secrets.md` (before rotating any secrets) ## 6. CLI Design Conventions **Command structure:** Follow `kubectl` / `gh` patterns. Structure is: ``` molecule [flags] ``` Examples: ``` molecule workspace create molecule workspace list molecule agent inspect ``` **Error output style:** - Errors go to stderr. Always. - Format: `[resource] [verb]: [specific error]` — not a stack trace. - Exit code 1 for errors; 0 for success; 2 for usage/flag errors. - Wrap platform API errors with the CLI context so they are actionable. **Flag conventions:** - Global flags ( `--output`, `--verbose`, `--config`) come before subcommands. - Boolean flags use `--flag` / `--no-flag` inversion where appropriate. - Environment variable overrides: prefer it. Flag → env var → default. - No single-letter flags unless they are universally understood (`-h`, `-v`, `-o`, `-f`). ## 7. Known Issues See `known-issues.md` at the repo root for the full tracked list. **Policy:** File a GitHub issue before patching silently. Do not merge a workaround without a linked issue. ## 8. Command Reference Full `molecule` command tree. All subcommands follow `molecule [flags]` pattern. ### Workspace Commands ``` molecule workspace create [--name ] [--tier <1-4>] [--template ] molecule workspace list molecule workspace inspect molecule workspace delete molecule workspace restart molecule workspace delegate molecule workspace audit ``` ### Agent Commands ``` molecule agent list [workspace-id] molecule agent inspect molecule agent send molecule agent peers ``` ### Platform Commands ``` molecule platform audit molecule platform health ``` ### Config Commands ``` molecule init # Bootstrap molecule.yaml in the current directory molecule config list # Show current config molecule config set molecule config get molecule config init # Alias for molecule init molecule config view # Print config file path and current values ``` ### Global Flags | Flag | Description | |------|-------------| | `--api-url ` | Platform API base URL (env: MOLECULE_API_URL) | | `--output`, `-o` | Output format: `table` (default), `json`, `yaml` | | `--verbose`, `-v` | Enable verbose (DEBUG-level) output to stderr | | `--config ` | Path to config file (default: `~/.config/molecule.yaml` or `./molecule.yaml`) | | `--help`, `-h` | Show help for any command | ### Error Codes All errors go to stderr with exit codes: - **0** — success - **1** — runtime error (platform API error, file system error) - **2** — usage error (missing required flag, bad argument, unknown subcommand) Error format: `[resource] [verb]: [specific message]` Examples: ``` molecule workspace delete abc123: workspace not found molecule agent send xyz: workspace_id unknown for agent "xyz" molecule: unknown subcommand "agen inspect" ``` ### Output Format Examples **text (default):** ``` Workspace: my-workspace ID: 550e8400-e29b-41d4-a716-446655440000 Status: online Tier: 2 Created: 2026-04-01T12:00:00Z ``` **json:** ```json {"id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-workspace", "status": "online", "tier": 2} ``` **yaml:** ```yaml id: 550e8400-e29b-41d4-a716-446655440000 name: my-workspace status: online tier: 2 ``` ## 9. Homebrew Tap Release Releases are published to the Molecule-AI/homebrew-tap tap. The GitHub Actions workflow handles the formula update automatically when a `v*` tag is pushed. To release via Homebrew tap: 1. Push a `v*` tag to GitHub 2. The GitHub Release workflow attaches a `molecule_*_darwin_arm64.tar.gz` and `molecule_*_darwin_amd64.tar.gz` to the release 3. The `brew формула` is updated by the workflow to point at the new release assets 4. Users install via: `brew install molecule-ai/tap/molecule` Do not manually edit the Homebrew formula. Let the workflow manage it. ## 10. Cross-Platform Binary Build Notes GoReleaser builds for these targets by default (see `.goreleaser.yml`): - `darwin/amd64` — Intel macOS - `darwin/arm64` — Apple Silicon macOS - `linux/amd64` — Linux x86_64 - `linux/arm64` — Linux ARM64 - `windows/amd64` — Windows x86_64 (.exe) Each target produces a compressed archive (`.tar.gz` on Unix, `.zip` on Windows) with: - `molecule` (or `molecule.exe`) binary - `completions/` dir with shell completion scripts (`bash`, `zsh`, `fish`, `powershell`) Install shell completions: ```bash # bash source <(molecule completion bash) # zsh molecule completion zsh > "${fpath[1]}/_molecule" # fish molecule completion fish | source ``` ## 11. Implementation Status (as of 2026-04-22) The CLI has a full command tree and 24 integration tests. Remaining items: - [ ] Workspace runtime client (for dev/proxy mode) - [ ] Workspace template config (`~/.config/molecule.yaml` scaffold by default) - [ ] `molecule completion` shell completion subcommands - [ ] `molecule workspace restart` — confirm API endpoint / status code handling - [ ] Cross-compile CI matrix (`.github/workflows/release.yml` currently uses plain `go build`) Done: - [x] `cmd/molecule/main.go` — entry point with Cobra root command - [x] Root command and global flags (`--verbose`, `--output`, `--config`, `--api-url`) - [x] `workspace create`, `workspace list`, `workspace inspect`, `workspace delete`, `workspace restart`, `workspace audit`, `workspace delegate` subcommands - [x] `agent list`, `agent inspect`, `agent send`, `agent peers` subcommands - [x] `platform audit`, `platform health` subcommands - [x] `init`, `config list`, `config get`, `config set`, `config init`, `config view` subcommands - [x] Control plane API client (`internal/client/platform.go`) - [x] `go test ./...` — 24 integration tests with httptest mock server - [x] `.goreleaser.yaml` with all 6 targets wired up **Platform constraint reminders (from `constraints-and-rules.md`):** - Postgres is the source of truth. CLI commands that mutate state ultimately write to Postgres via the control plane. - Bundles must never contain secrets. Any config templating must enforce this. - Workspace templates are generic by default. Platform-provided templates are used; do not bake environment-specific values into templates. --- ## Platform Conventions (Inherited) These apply to all platform repos including this one: - **Cron discipline:** Read `cron-learnings` before reviewing PRs. After each triage cycle, write a 1-line reflection to `.claude/per-tick-reflections.md`. - **CLAUDE.md / PLAN.md sync:** PRs that touch `CLAUDE.md` or `PLAN.md` are always noteworthy — review them carefully. - **Secrets rotation:** Before rotating any secrets, read `docs/runbooks/saas-secrets.md`.