substructure.ai
DocsBlogStar on GitHub

CLI

Updated Jul 14, 2026View as Markdown

subs is the command-line front end to the engine. It runs turns locally against your worker and manages a hosted cloud app.

Install

npm install -g @substructure.ai/cli

Running a turn

subs run sends one input to the engine, streams the turn, and exits.

export ANTHROPIC_API_KEY=sk-ant-...
subs run \
    --worker-url http://localhost:4444 \
    --agent my-agent \
    --provider anthropic \
    --output pretty \
    --input '{"type":"client.message","message":{"role":"user","content":"hi"}}'
FlagMeaning
--inputA ClientInput JSON. Required. Its type picks submit, resume, or settle.
--agentThe agent id the worker routes on.
--worker-urlWhere the engine POSTs decisions. Default http://localhost:3000/agent.
--sessionResume a session. Omit to start one; the id is printed.
--providerEngine-run LLM provider: anthropic, openai, or openrouter.
--outputag-ui (default), jsonl, or pretty.
--dbSQLite file. Default data.db.

After a turn it prints the command to continue the session.

Local server

subs serve runs the engine as an HTTP server.

subs serve --dev --provider anthropic --worker-url http://localhost:4444

--dev disables auth for local use. It also takes --host, --port, and --db.

Cloud

Sign in and manage a hosted app.

CommandDoes
subs login / logout / whoamiAuthenticate.
subs appsList, create, show, rename, delete apps.
subs keysCreate and revoke API keys.
subs sessionsList sessions and stream their events.
subs webhookSet the worker URL and signing secret.
subs linkPin an org and app in substructure.toml.

Next