2ee3b42d6b
This PR is README-only. The Go module-path migration (github.com/Molecule-AI/molecule-cli → git.moleculesai.app/molecule-ai/ molecule-cli in go.mod + every internal import) is filed separately as a cross-repo Go-module migration PR (parked follow-up on internal#37). Changes here: - Install section: keep the go install command but switch to the Gitea path + add a "Migration in progress" callout pointing at the build-from-source workaround until the Go-module PR lands. - Releases link: removed the broken github.com/.../releases URL (releases pipeline being restored on Gitea Actions). - RFC #10 link: rewritten to git.moleculesai.app form with note that the original issue lived on the suspended GitHub org. Files NOT touched in this PR (left for the cross-repo Go-module PR): - go.mod (module declaration) - 25+ .go files with github.com/Molecule-AI/molecule-cli/internal/... import paths - known-issues.md L96 (describes current module path; consistent with go.mod) - CLAUDE.md L37 (declares current module path; consistent with go.mod) These edits maintain consistency with go.mod while documenting the upcoming change to users. Bundling them with the doc edit would create a half-state where docs say one path and go.mod says another. Refs: molecule-ai/internal#37, molecule-ai/internal#38
104 lines
3.5 KiB
Markdown
104 lines
3.5 KiB
Markdown
# molecule-cli
|
||
|
||
Command-line companion for [Molecule AI](https://moleculesai.com). 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
|
||
|
||
> **Migration in progress** (2026-05-07): the `github.com/Molecule-AI`
|
||
> org was suspended on 2026-05-06 and is permanently gone. The
|
||
> canonical SCM is now Gitea at
|
||
> [`git.moleculesai.app/molecule-ai`](https://git.moleculesai.app/molecule-ai).
|
||
>
|
||
> The `go install` path below requires the Go module-path migration to
|
||
> land first (separate cross-repo PR — see `internal#37` parked
|
||
> follow-up). Until then, build from source:
|
||
>
|
||
> ```bash
|
||
> git clone https://git.moleculesai.app/molecule-ai/molecule-cli.git
|
||
> cd molecule-cli
|
||
> go build -o molecule ./cmd/molecule
|
||
> ```
|
||
>
|
||
> Once the Go module-path migration lands:
|
||
|
||
```bash
|
||
go install git.moleculesai.app/molecule-ai/molecule-cli/cmd/molecule@latest
|
||
```
|
||
|
||
Releases ship Linux/macOS/Windows × amd64/arm64 archives plus a sha256
|
||
checksums file (see `.goreleaser.yaml`). Releases pipeline (Gitea
|
||
Actions) is being restored as part of the post-suspension recovery; in
|
||
the interim, build from source per the migration note above.
|
||
|
||
## Quick start — connect an external workspace
|
||
|
||
When you create a workspace with `runtime: external`, the platform returns
|
||
a per-workspace token. Run:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```bash
|
||
# 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)
|
||
--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.
|
||
|
||
## Other subcommands
|
||
|
||
```
|
||
molecule agent list / inspect agent sessions
|
||
molecule config view / set CLI defaults
|
||
molecule completion generate shell completions
|
||
```
|
||
|
||
The full M1 design is in [RFC #10](https://git.moleculesai.app/molecule-ai/molecule-cli/issues/10) (originally filed on the suspended GitHub org; the issue may be re-filed on Gitea — check the issue tracker for the live discussion).
|
||
|
||
## License
|
||
|
||
Business Source License 1.1 — © Molecule AI.
|