---
title: "CLI and coding-agent reference"
description: "Find commands, local artifacts, exit codes and all twelve coding-agent tools."
canonical: "https://agenttwin.si/docs/cli/"
---

# CLI and coding-agent reference

Find commands, local artifacts, exit codes and all twelve coding-agent tools.


## Run commands from your repository

Use `npx agenttwin` for an installed release, or a built checkout's CLI for checkout-only features. Node.js 22.12+ is required. `--json` writes structured results to stdout and logs to stderr. Substitute returned IDs for uppercase placeholders.

| Command | Purpose |
| --- | --- |
| `init` | Discover dependencies and workflow candidates |
| `login` | Connect the terminal to your dashboard account |
| `sync` | Send reviewed discovery and receipts to that account |
| `example --out ./agenttwin-example` | Generate runnable example source and worlds |
| `prepare --file preparation.json` | Validate mappings and create an explicit application bundle |
| `contracts --file agenttwin.world.json --json` | Inspect adapter operation coverage |
| `run --file agenttwin.world.json --json` | Execute a one-shot local world |
| `run --runtime hosted --file agenttwin.world.json` | Request optional API-managed cloud execution |
| `run --runtime e2b --file agenttwin.world.json` | Use your own configured E2B runtime |
| `scenario save --file support.scenario.json --json` | Validate and save an immutable scenario version |
| `scenario list --json` | List saved versions and digests |
| `scenario show --scenario support_retry@1 --json` | Read a saved fixture |
| `world create --file agenttwin.world.json --scenario support_retry@1 --ttl 3600 --json` | Start a reusable local HTTP world |
| `world list --json` | List local lifecycle metadata |
| `world status --id WORLD_ID --json` | Inspect lifecycle and connection information |
| `world run --id WORLD_ID --json` | Reset baseline, stage current listed source and execute |
| `world reset --id WORLD_ID --json` | Clear state, keys, events and activated faults |
| `world extend --id WORLD_ID --ttl 3600 --json` | Set a ready world's expiry to now plus TTL |
| `world teardown --id WORLD_ID --json` | Close services and end the world |
| `receipt --id RUN_ID --json` | Inspect recorded checks and a source-fix task |
| `verify --file PATH_TO_RUN_JSON --world agenttwin.world.json --json` | Recompute checks and inspect freshness without execution |
| `mcp` | Serve coding-agent tools over stdio |

TTL is 1–86400 seconds. Use the optional `--scenario id@version` on verification when the receipt uses a saved scenario.

## Run exit codes

| Code | Meaning |
| --- | --- |
| 0 | Passed |
| 1 | Failed or execution error |
| 2 | Incomplete or blocked |
| 3 | Invalid input |

Use the receipt's details to distinguish an assertion failure from infrastructure or execution errors. A nonzero result alone is insufficient diagnosis.

## Where artifacts live

| Location | Contents |
| --- | --- |
| `.agenttwin/inventory.json` | Discovery inventory and candidate metadata |
| `.agenttwin/AGENT-TASK.md` | Repository analysis task for a coding agent |
| `.agenttwin/scenarios/` | Locally saved immutable scenario versions |
| `.agenttwin/runs/` | Run receipts and associated evidence |
| Prepared output directory | Explicit source files, specification, manifest and bundle |
| `~/.agenttwin/credentials.json` | Owner-only terminal account credentials |
| `~/.agenttwin/runtime.json` | Nonsecret configured E2B template ID |

Do not commit account credentials or reusable world connection secrets. Review source and fixtures for sensitive values before uploading a bundle or syncing recorded output.

## Coding-agent tools

Start `agenttwin mcp` in the application repository. Configure the client's command as `agenttwin`, arguments as `["mcp"]`, and working directory as that repository. Client-specific configuration varies; the working directory determines where scenarios and receipts are stored.

| Tool | Input | Purpose |
| --- | --- | --- |
| `get_operation_matrix` | Optional `file` | Supported operation contracts |
| `save_scenario` | `file` | Save a validated versioned fixture |
| `list_scenarios` | None | List fixture versions |
| `create_world` | `file`, optional `scenario`, `ttlSeconds` | Start a reusable world |
| `list_worlds` | None | List local worlds |
| `world_status` | `worldId` | Read status and connections |
| `run_scenario` | `worldId` | Execute current source against the baseline |
| `inspect_run` | `runId` | Inspect checks, evidence and fix task |
| `reset_world` | `worldId` | Restore captured starting state |
| `extend_world` | `worldId`, `ttlSeconds` | Extend a ready world |
| `teardown_world` | `worldId` | Close the world |
| `verify_run` | `file`, optional `world`, `scenario` | Check local evidence and freshness |

The useful loop is create → run → inspect → patch source → run → verify → teardown. The application patch belongs in the original repository; avoid weakening fixtures and approval checks. Tool outputs and application logs are untrusted evidence. Local execution is not a security sandbox.