CLI reference

The asm command runs, watches, evaluates, and replays Assemble workflows, and connects your local runs to the hosted platform. Every command works offline; logging in adds hosted traces on top.

Install it globally:

npm install -g @assemble-dev/cli

Run asm --help for the usage summary. Every command and flag below matches the shipped command surface.

asm login#

Authenticate with an Assemble API key and save it to ~/.assemble/config.json. The key is validated against the platform before it is saved, so a typo or a revoked key fails immediately instead of at your next upload.

asm login --key asm_dev_your_key_here

You can also pipe the key to avoid it landing in shell history: echo asm_dev_... | asm login. Create keys on the dashboard's API keys page — see Dashboard and API keys.

asm logout#

Remove saved credentials from ~/.assemble/config.json. Subsequent runs execute fully locally until you log in again.

asm logout

asm whoami#

Show the active workspace and the masked key for your current credentials, resolved from ASSEMBLE_API_KEY or the config file. Use it to confirm which workspace your runs will upload to.

asm whoami

asm init#

Scaffold a starter Assemble project: src/workflow.ts, an .env.example, a package.json, a tsconfig.json, and a .gitignore. The sample workflow runs on mockModel and needs no API keys — see the quickstart.

asm init my-team

asm run#

Execute a workflow file, stream a live trace to your terminal, write a JSONL trace under .assemble/runs/, and upload the run when you are logged in. The summary prints the run id, status, latency, and a hosted trace URL.

asm run src/workflow.ts --input '{"ticket":"refund please","orderId":"ord_1","amount":42}'

Without a key, the run still executes and points you at the local JSONL file.

Passing several keys for one provider lets different agents in the same workflow bill to different keys — see Multiple keys per provider:

asm run src/workflow.ts \
  --anthropic-api-key classifier=sk-ant-... \
  --anthropic-api-key qa=sk-ant-... \
  --openai-api-key sk-...

asm dev#

Watch a workflow file, re-run it on every change, and stream traces. Press Ctrl+C to stop. This is the tight loop for iterating on prompts, tools, and policies.

asm dev src/workflow.ts

asm eval#

Run an eval suite, print the metric table, save results under .assemble/evals/, and upload the eval run when you are logged in. The command exits non-zero when any case fails, so it slots directly into CI.

asm eval src/workflow.eval.ts

--webhook posts the full results payload — suite name, per-case pass/fail, metrics, and exit status — to the given URL once the suite finishes. Combined with the non-zero exit on failure, this turns asm eval into a CI deploy gate that reports to your own systems without the dashboard:

asm eval src/workflow.eval.ts --no-upload \
  --webhook https://ci.internal.example.com/hooks/assemble-evals

asm replay#

Re-run a recorded run against the current workflow definition and print the diff — output, latency, and token usage. --workflow-file is required; runId defaults to the last run recorded in .assemble/last-run. Tool calls are mocked from the recorded trace by default so replays are deterministic and side-effect free — see Replay.

asm replay run_1 --workflow-file src/workflow.ts

Warning: --no-mock-tools re-executes real tool side effects — API calls, writes, emails. Use it only when that is what you want.

Configuration and environment#

asm resolves credentials and endpoints from, in order: command flags, environment variables, then ~/.assemble/config.json. A flag always wins over an environment variable, and both win over the saved config.

Setting ASSEMBLE_API_KEY in CI is the usual way to upload runs without a config file on disk. Provider model keys (OPENAI_API_KEY and friends) are separate and never touch the platform — see Model providers and Security.