molecule-cli/README.md

molecule-cli

Command-line companion for Molecule AI. The primary entry point for external-runtime workspaces — bridge a workspace to a local agent backend (Claude Code, an arbitrary shell command, or a mock for CI).

Install

go install github.com/Molecule-AI/molecule-cli/cmd/molecule@latest

Or download a binary from Releases. Releases ship Linux/macOS/Windows × amd64/arm64 archives plus a sha256 checksums file (see .goreleaser.yaml).

Quick start — connect an external workspace

When you create a workspace with runtime: external, the platform returns a per-workspace token. Run:

export MOLECULE_API_URL=https://your-tenant.staging.moleculesai.app
export MOLECULE_WORKSPACE_TOKEN=ws_secret_xxx

molecule connect ws_abcdef

connect registers the workspace, starts heartbeating, polls the platform for inbound A2A messages, and dispatches each message to the selected backend. Replies are posted back over the platform API.

Backends

--backend selects how A2A messages are handled. Three are built in:

Name	What it does
claude-code	Default. Invokes claude -p <message> for each turn (claude-code SDK).
exec	Runs an arbitrary shell command (--backend-opt cmd=...). Stdout = reply.
mock	Echo backend for CI / smoke tests.

Backend options are passed via repeatable --backend-opt KEY=VALUE:

# 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' \
  --backend-opt timeout=5m

Other useful flags

--mode poll|push         delivery mode (default: poll; push is M4, not yet implemented)
--interval-ms 2000       poll cadence
--since-secs 60          initial activity cursor lookback
--token TOKEN            override MOLECULE_WORKSPACE_TOKEN
--dry-run                build backend + print summary, exit

State (the activity cursor) is persisted to ~/.config/molecule/state/<workspace-id>.json (mode 0600) so a restart resumes from the last delivered message.

Note: poll-mode dispatch into backends works end-to-end. Posting the backend's reply back to the canvas-origin sender is still wired as a TODO (see internal/connect/connect.go — M1.3); platform-API replies for non-canvas A2A flow correctly.

Command reference

The full top-level tree:

molecule
├── workspace    list / create / inspect / delete / restart / audit / delegate
├── agent        list / inspect / send / peers
├── platform     audit / health
├── config       list / get / set / init / view
├── connect      bridge an external workspace to a local backend
├── init         scaffold a molecule.yaml in the current directory
└── completion   emit shell completion script (bash | zsh | fish | powershell)

Global flags (apply to every subcommand): --api-url, --config, -o/--output table|json|yaml, -v/--verbose.

molecule workspace

Manage Molecule AI workspaces.

• workspace list — list all workspaces in the org.

  molecule workspace list
  molecule workspace list -o json
  

• workspace create --name <name> [flags] — create a workspace. Flags: --role, --runtime, --template, --parent-id, --workspace-dir, --tier.

  molecule workspace create --name pm-bot --role pm --runtime claude-code
  

• workspace inspect <workspace-id> — show full details for a workspace.

  molecule workspace inspect ws_01HF2K...
  

• workspace delete <workspace-id> — delete a workspace (irreversible).

  molecule workspace delete ws_01HF2K...
  

• workspace restart <workspace-id> — trigger a restart.

  molecule workspace restart ws_01HF2K...
  

• workspace audit — workspaces + agents report grouped by status.

  molecule workspace audit -o yaml
  

• workspace delegate <workspace-id> <target-workspace-id> <task> — enqueue a non-blocking delegation from one workspace to another.

  molecule workspace delegate ws_pm ws_research "summarize last week"
  

molecule agent

Inspect and interact with agents.

• agent list [workspace-id] — list all agents, optionally scoped to one workspace.

  molecule agent list
  molecule agent list ws_01HF2K...
  

• agent inspect <agent-id> — show full details for an agent.

  molecule agent inspect agent_abc
  

• agent send <agent-id> <message> — send a one-shot A2A message to an agent and print the reply.

  molecule agent send agent_abc "what's the deploy status?"
  

• agent peers <workspace-id> — list peer workspaces reachable from the given workspace.

  molecule agent peers ws_01HF2K...
  

molecule platform

Platform-level operations.

• platform audit — full audit: workspaces, agents, delegation counts per workspace.

  molecule platform audit -o json
  

• platform health — check /health and version (falls back to raw probe on older platforms).

  molecule platform health
  

molecule config

View and manage CLI configuration. Values resolve in order: env vars > config file > defaults.

• config list — list all known config keys + effective values + source.
• config get <key> — print a single config value.
• config set <key> <value> — write a key to ~/.config/molecule.yaml.
• config init — scaffold a default molecule.yaml in the current dir.
• config view — print the active config file with annotations.

molecule config set api_url https://your-tenant.staging.moleculesai.app
molecule config get api_url
molecule config list

molecule connect

See Quick start above. Push mode (--mode push) is reserved for M4 and currently exits with a clear error — use the default --mode poll.

molecule init

Bootstrap a workspace by scaffolding molecule.yaml in the current directory. Use --force to replace an existing file.

molecule init
molecule init --force

molecule completion

Emit a shell completion script. The shell name is a positional arg — one of bash, zsh, fish, powershell.

# bash
source <(molecule completion bash)

# zsh
source <(molecule completion zsh)

# fish
molecule completion fish | source

# PowerShell
molecule completion powershell | Out-String | Invoke-Expression

The full M1 design is in RFC #10.

License

Business Source License 1.1 — © Molecule AI.