Engineering
molecule-cli: the command-line tool for managing your Molecule AI agent organization
molecule-cli brings workspace lifecycle, org admin, secrets, and runtime controls to the terminal.
We shipped molecule-cli — the command-line companion to the Molecule AI control plane. It covers two distinct jobs: bridging external-runtime workspaces to local backends, and managing your Molecule AI organization from the terminal.
Install
go install go.moleculesai.app/cli/cmd/molecule@latestThe vanity import path resolves via the Molecules AI go-get responder to the canonical source at git.moleculesai.app. When we move SCMs again, no install command changes.
The connect command: external-runtime workspaces
The first job is molecule connect. When you create a workspace with runtime: external, the platform hands you a per-workspace token. connect does everything after that:
molecule connect ws_abcdefIt registers the workspace, starts heartbeating, polls the platform for inbound A2A messages, and dispatches each turn to a backend. Replies go back over the platform API. Three backends are built in:
| Backend | What it does |
|---|---|
claude-code (default) | Invokes claude -p <message> for each turn |
exec | Runs an arbitrary shell command; stdout is the reply |
mock | Echo backend for CI / smoke tests |
# Claude Code with a 10-minute per-turn timeout
molecule connect ws_abc \
--backend claude-code \
--backend-opt timeout=10m
# Generic shell handler
molecule connect ws_abc \
--backend exec \
--backend-opt cmd='./my-agent.sh'The full design for connect — activity cursors, push mode, session recovery — is documented in the RFC at molecule-cli/issues/10.
Management verbs: org, workspace, secret
The second job is the management command tree, added in PR #13 (feat(cli): fix runHTTP auth bug + add management verbs). The verbs mirror the platform API one-to-one:
molecule org list | get | create | export
token list | create | revoke | allowlist
molecule workspace list | create | inspect | delete
restart | pause | resume
audit | delegate <target-workspace-id> <task>
budget | billing-mode | token mint
molecule secret ws list | set | delete
org list | set | delete
molecule template list | import | refresh
molecule bundle export | import
molecule events
molecule approvalsworkspace delegate is the CLI surface for A2A delegation — it dispatches a task to another workspace without blocking the caller (non-blocking by design, matching the platform’s own async delegation contract).
The auth bug that blocked every management call
The management verbs were shipped alongside a fix that matters: before PR #13, runHTTP — the internal helper every management command routes through — sent no Authorization header. Any call to a hardened tenant 401’d silently.
The fix attaches the expected auth headers on every management request, with the tenant-routing header included when set. Headers are omitted when the env vars are absent so fresh self-host and dev tenants keep working without extra config.
A regression test (TestRunHTTP_SetsAuthHeader) asserts the header is present and is proven load-bearing — it fails with Authorization header = "" when the fix is reverted. If you ran management calls before PR #13 and got 401s, that was the cause; the fix is in the current build.
What’s wired to the platform API
Each management verb targets the documented endpoint at the correct auth tier. The source of truth is the live workspace-server router.go + handlers and the controlplane orgs handler — not a spec doc that might lag the implementation. The commit message for PR #13 notes that the parallel feat/openapi-management-spec branch did not exist in molecule-core at the time, so the verbs were reconciled to the actual handler source instead.
Next
molecule connect poll mode is the supported path today; push mode is the M4 work (tracked in molecule-cli/issues/10). The management verbs cover the platform API surface at the time of PR #13 — additional endpoints (marketplace, billing) will follow as they stabilize.