From 3afa0d8c0a0a658f8816d43a34afd93e1830700d Mon Sep 17 00:00:00 2001 From: Molecule AI SDK-Dev Date: Wed, 22 Apr 2026 07:02:39 +0000 Subject: [PATCH] docs(cli): sync CLAUDE.md command tree with actual implementation - Update Section 2 build/test commands to reflect current state - Rename Section 8 command tree from "mol" to "molecule" throughout - Add --api-url flag to Global Flags table, remove --platform-url - Update error examples to use "molecule" command name - Replace Section 11 "Early / Stub" checklist with accurate status - Mark all implemented commands and tests as done, keep remaining todos Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 89 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 42 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 605e35c..0fae79a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,18 +20,16 @@ This CLI is the primary user-facing tool for interacting with the Molecule AI pl ## 2. Build, Test, and Local Run ```bash -# Build the binary to ./bin/molecule (or $GOBIN/molecule) +# Build the binary to ./bin/molecule go build -o bin/molecule ./cmd/molecule -# Run tests (none yet; add as commands are implemented) +# Run the test suite (24 integration tests) go test ./... -# Run the CLI locally (requires platform env vars — see Section 5) +# Run the CLI ./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`) @@ -124,50 +122,50 @@ See `known-issues.md` at the repo root for the full tracked list. ## 8. Command Reference -Full `mol` command tree. All subcommands follow `molecule [flags]` pattern. +Full `molecule` command tree. All subcommands follow `molecule [flags]` pattern. ### Workspace Commands ``` -mol workspace create [--name ] [--tier <1-4>] [--template ] -mol workspace list -mol workspace inspect -mol workspace delete -mol workspace restart -mol workspace delegate --task "" [--sync|--async] -mol workspace audit +molecule workspace create [--name ] [--tier <1-4>] [--template ] +molecule workspace list +molecule workspace inspect +molecule workspace delete +molecule workspace restart +molecule workspace delegate +molecule workspace audit ``` ### Agent Commands ``` -mol agent list -mol agent inspect -mol agent send --message "" -mol agent peers +molecule agent list [workspace-id] +molecule agent inspect +molecule agent send +molecule agent peers ``` ### Platform Commands ``` -mol platform audit [--url ] [--token ] -mol platform health +molecule platform audit +molecule platform health ``` ### Config Commands ``` -mol init # Bootstrap mol.yaml in the current directory (primary entry point) -mol config list # Show current config -mol config set -mol config get -mol config init # Alias for mol init (bootstrap ~ /.config/molecule/cli.yaml) -mol config view # Print config file path and current values +molecule init # Bootstrap molecule.yaml in the current directory +molecule config list # Show current config +molecule config set +molecule config get +molecule config init # Alias for molecule init +molecule 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 to config file (default: `~/.config/molecule/cli.yaml`) | -| `--platform-url ` | Override `MOLECULE_API_URL` for this invocation | +| `--api-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 to config file (default: `~/.config/molecule.yaml` or `./molecule.yaml`) | | `--help`, `-h` | Show help for any command | ### Error Codes @@ -180,9 +178,9 @@ 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" +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 @@ -244,19 +242,26 @@ molecule completion zsh > "${fpath[1]}/_molecule" molecule completion fish | source ``` -## 11. Early / Stub Repo Status +## 11. Implementation Status (as of 2026-04-22) -This repo was initialized 2026-04-16. The following is needed before a functional CLI exists: +The CLI has a full command tree and 24 integration tests. Remaining items: -- [ ] `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 -- [x] `molecule init` (bootstrap local workspace config) +- [ ] 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.