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

```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 <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:**
```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`.