Command line
Open a session, stream a command, transfer files, and connect over SSH.
Build from the repository root, then invoke the local CLI:
npm run build
node packages/cli/dist/index.js --helpAfter installing the local package tarballs, the executable is named assemble and can be run with npx assemble in your project. The package has not been published to npm.
Set ASSEMBLE_API_KEY and ASSEMBLE_BASE_URL in your environment. --base-url overrides the URL. --json produces JSON metadata or newline-delimited JSON events for scripts.
The examples below use assemble to keep commands short. Use node packages/cli/dist/index.js instead when running from this repository.
| Command | Purpose |
|---|---|
assemble open my-project --image terminal | Create or reopen a named session |
assemble list --limit 20 | List one page; --after continues a cursor |
assemble exec ID 'python3 --version' | Run one quoted shell command and stream output |
assemble read ID notes.txt | Write file bytes to stdout |
assemble write ID notes.txt ./local-notes.txt | Upload a local file |
assemble write ID notes.txt - | Upload stdin |
assemble ls ID | List the session root |
assemble ssh ID --expires-in 15 | Print a temporary SSH connection command |
assemble ssh ID --revoke ACCESS_ID | Revoke a grant |
assemble pause ID / assemble resume ID | Control compute lifecycle |
assemble delete ID | Permanently remove VM and filesystem |
Replace ID with the session UUID. An execution supports --cwd, --timeout in seconds, and repeated --env NAME=value. Avoid putting secret values directly in shell history; use your harness or application credential flow where appropriate.
Exit behavior
exec forwards stdout and stderr, then uses the process exit code. A failed terminal state with no nonzero exit code exits with 1. Ctrl+C requests cancellation and exits with 130; confirm process state before assuming an interrupted connection stopped the VM command.
Permanent deletion asks you to type the session name in an interactive terminal. Use --yes only when you intend to delete all retained resources; it is required for noninteractive deletion.
Provided harness
assemble agent ID 'Summarize this project in summary.md'The service operator configures the default provider and model. To override them, add both --provider openai and --model gpt-4.1, choosing a model available to the operator. This starts a fresh agent conversation. Ctrl+C stops the request. Use --json to receive structured agent progress events.