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

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