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 (or $GOBIN/molecule)
go build -o bin/molecule ./cmd/molecule

# Run tests (none yet; add as commands are implemented)
go test ./...

# Run the CLI locally (requires platform env vars — see Section 5)
./bin/molecule --help

There is no main.go or cmd/molecule/main.go yet. Creating it is the first implementation task. The module path will be auto-detected from go.mod.

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 mol command tree. All subcommands follow molecule <resource> <verb> [flags] pattern.

Workspace Commands

mol workspace create [--name <name>] [--tier <1-4>] [--template <template-id>]
mol workspace list
mol workspace inspect <workspace-id>
mol workspace delete <workspace-id>
mol workspace restart <workspace-id>
mol workspace delegate <workspace-id> --task "<prompt>" [--sync|--async]
mol workspace audit <workspace-id>

Agent Commands

mol agent list <workspace-id>
mol agent inspect <agent-id>
mol agent send <agent-id> --message "<text>"
mol agent peers <agent-id>

Platform Commands

mol platform audit [--url <platform-url>] [--token <api-token>]
mol platform health

Config Commands

mol config list        # Show current config
mol config set <key> <value>
mol config get <key>
mol config init        # Bootstrap ~/.config/molecule/cli.yaml
mol config view        # Print config file path and current values

Global Flags

Flag	Description
--output, -o	Output format: text (default), json, yaml
--verbose, -v	Increase verbosity (repeat for debug level)
--config <path>	Path to config file (default: ~/.config/molecule/cli.yaml)
--platform-url <url>	Override MOLECULE_API_URL for this invocation
--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:

mol workspace delete abc123: workspace not found
mol agent send xyz: authentication failed: invalid API token
mol: 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. Early / Stub Repo Status

This repo was initialized 2026-04-16. The following is needed before a functional CLI exists:

• cmd/molecule/main.go — entry point with root command
• Root command and global flags (--verbose, --output, --config)
• workspace create, workspace list, workspace delete subcommands
• agent inspect, agent list subcommands
• Control plane API client (initialized with MOLECULE_API_URL)
• Workspace runtime client (for dev/proxy mode)
• Configuration file (e.g., ~/.config/molecule/cli.yaml) — workspace template per platform rules
• Unit tests for core command logic
• molecule init (bootstrap local workspace config)

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.