# 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. Implemented

- [x] `cmd/molecule/main.go` — entry point with root command
- [x] Root command and global flags (`--verbose`, `--output`, `--config`)
- [x] `workspace create`, `workspace list`, `workspace delete` subcommands
- [x] `agent inspect`, `agent list` subcommands
- [x] 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`.