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: Core commands implemented. 32 integration tests in cmd/molecule/molecule_test.go.

---

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 — uses httptest.Server fixtures, no live platform required
go test ./...

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

3. Go Module Conventions

Module path: go.moleculesai.app/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. Implemented

• 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 (32 integration tests)
• 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.