molecule-cli/CLAUDE.md

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

# 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:

# 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 <resource> <verb> [flags]

Examples:

molecule workspace create
molecule workspace list
molecule agent inspect <agent-id>

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 <resource> <verb> [flags] pattern.

Workspace Commands

molecule workspace create [--name <name>] [--tier <1-4>] [--template <template-id>]
molecule workspace list
molecule workspace inspect <workspace-id>
molecule workspace delete <workspace-id>
molecule workspace restart <workspace-id>
molecule workspace delegate <workspace-id> <target-id> <task>
molecule workspace audit

Agent Commands

molecule agent list [workspace-id]
molecule agent inspect <agent-id>
molecule agent send <agent-id> <message>
molecule agent peers <workspace-id>

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 <key> <value>
molecule config get <key>
molecule config init      # Alias for molecule init
molecule config view     # Print config file path and current values

Global Flags

Flag	Description
--api-url <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>	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:

{"id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-workspace", "status": "online", "tier": 2}

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
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:

• cmd/molecule/main.go — entry point with Cobra root command
• Root command and global flags (--verbose, --output, --config, --api-url)
• workspace create, workspace list, workspace inspect, workspace delete, workspace restart, workspace audit, workspace delegate subcommands
• agent list, agent inspect, agent send, agent peers subcommands
• platform audit, platform health subcommands
• init, config list, config get, config set, config init, config view subcommands
• Control plane API client (internal/client/platform.go)
• go test ./... — 24 integration tests with httptest mock server
• .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.