sw command line | StateWeave Docs

Reference

sw command line

sw drives your StateWeave workspace from a shell: sandboxes, tasks and tests, runs of your agent, and the skills that let a coding agent do all of it. python -m stateweave is the same command.

Shell

sw

--help

sw

sandbox

--help

# every command and subcommand has its own

Install and sign in

Shell

pip

install stateweave-sdk

sw

--version

# sw 0.6.3

The package needs Python 3.10 or later and nothing beyond its standard library. It also holds the Python SDK .

Configuration

Every command needs your workspace's address and an API key. For each of the two, the first of these that is set wins:

STATEWEAVE_URL and STATEWEAVE_API_KEY in the environment.

What sw login kept in ~/.config/stateweave/config.json , or in $XDG_CONFIG_HOME/stateweave/config.json when that variable is set, or in the file STATEWEAVE_CONFIG names. The file is readable only by you.

With no address set anywhere, sw uses http://127.0.0.1:8700 , which is not your workspace, so set the address first. A workspace's address looks like https://acme.app.stateweave.net .

Shell

export

STATEWEAVE_URL=https://acme.app.stateweave.net

export

STATEWEAVE_API_KEY=sw_…

sw login

Shell

sw

login [--url URL] [--key KEY]

Checks the key with the workspace, then keeps the address and the key. Without --url it uses STATEWEAVE_URL , else the address kept before, else it asks for the address. Without --key it asks for the key and does not echo it. If the workspace refuses the key, nothing is kept and the command exits 1.

Make an API key in your workspace under Connect your agent (the key button). It starts with sw_ and is shown once.

Shell

sw

login

--url

https://acme.app.stateweave.net

--key

sw_…

sw whoami

Prints the address in use and the key's name and id.

sw logout

Deletes the file sw login wrote. Environment variables are not touched.

Sandboxes

A sandbox is the apps' data. SB below is a sandbox's id, p-… . A new sandbox is blank and in edit mode; you fill it, then switch it to test mode, which keeps a version that every run starts from. See Sandboxes and Fill a sandbox .

sw sandbox new

Shell

sw

sandbox new NAME

--apps

APP,APP [--owner-name OWNER] [--owner-email EMAIL] [--time-zone ZONE]

Makes a blank sandbox in edit mode and prints its id. Each app holds only its account, the owner and the owner's token.

Option Description
NAME Required. What to call the sandbox; the first 80 characters are kept.
--apps Required. Comma-separated app names: slack , gmail , google_calendar , google_sheets , google_drive , salesforce , shopify , zendesk , whatsapp , microsoft_teams , stripe , hubspot , github .
--owner-name The owner's name. Default Sandbox Owner .
--owner-email The owner's email address. Default owner@example.com .
--time-zone An IANA time zone name. Default UTC .

Shell

sw

sandbox new

"Acme Support"

--apps

slack,zendesk

--owner-name

"Ada Lovelace"

--owner-email

ada@acme.example

sw sandbox ls

Every sandbox, newest first, one per line: id, mode, how many versions it has ( v0 , v1 , …), the day it last changed (its latest version, else when it was made; UTC), apps and title. The workspace's Starter sandbox ends with (starter: not counted against the plan) .

sw sandbox show

Shell

sw

sandbox show SB

The sandbox's id, title and status, then per app whether it is up and how many records of each kind it holds, then its mode, its number of versions and its owner's email.

sw sandbox connect

Shell

sw

sandbox connect SB [--env]

Edit mode only. Starts the sandbox's own apps and prints, as JSON, sandbox , mode , persona (the owner's handle), and per app its base_url , endpoints , the owner's credentials and its mcp server, then env : the same as environment variables. What you write through these addresses is the sandbox's data. With --env it prints only the variables, as export lines for a shell:

Shell

eval

"$(sw sandbox connect p-7d21c4 --env)"

echo

"$STATEWEAVE_SLACK_URL"

The variables are STATEWEAVE_<APP>_URL , STATEWEAVE_<APP>_MCP_URL for an app with an MCP server, and one STATEWEAVE_<APP>_<KIND>_TOKEN per credential. See Apps and credentials . In test mode the command fails: open a twin run instead ( Python open_twins() , or the API ).

sw sandbox actions

Shell

sw

sandbox actions SB

StateWeave's own actions for each of the sandbox's apps: what happens in the real world outside the app's API, such as a person joining a Slack workspace or a customer writing on WhatsApp. Each line shows the app, the action and its params as flags, ? marking an optional one; the next line says what it does.

sw sandbox act

Shell

sw

sandbox act SB APP ACTION [--PARAM VALUE …]

Does one action, in edit mode, and prints {"action", "app", "results"} as JSON: the app's answer to each step. Give each param as --PARAM VALUE ; a _ in a param's name may be written - , and a value that starts with [ is read as a JSON list.

Shell

sw

sandbox act p-7d21c4 slack add_person

--handle

grace

--name

"Grace Hopper"

--email

grace@acme.example

sw

sandbox act p-7d21c4 whatsapp test_recipients

--add

'["15550001111"]'

sw sandbox generate

Shell

sw

sandbox generate SB

--describe

TEXT [--company NAME] [--people N] [--weeks N] [--templates]

Generates a made-up company's data into a blank sandbox, then follows the generation, printing each step to standard error, and ends with what each app holds. It is refused once the sandbox holds anything (a version, an earlier generation, or a change in edit mode). Exits 0 when the sandbox ends ready or partial , 1 when it ends failed . --describe , --company , --people , --weeks and --templates are as for sw env new .

sw sandbox changes

Shell

sw

sandbox changes SB

Prints {"mode", "changes", "versions"} as JSON: per app how many records edit mode added, changed and removed that are not in a version yet, and the sandbox's versions. changes is empty in test mode.

sw sandbox mode

Shell

sw

sandbox mode SB edit|test

test stops the sandbox's apps and, when anything changed since the last version, keeps what they hold as a new version. Tests whose apps changed then need a re-check. edit starts the apps again from the latest version so you can go on changing them. Prints the mode and the latest version's number. Refused while the sandbox is writing tests, re-checking them or has runs going.

Shell

sw

sandbox mode p-7d21c4 test

# p-7d21c4 is in test mode; version 1

sw sandbox rename

Shell

sw

sandbox rename SB NAME

Changes the sandbox's name only. Prints SB is now called NAME . Refused while it is generating.

sw sandbox copy

Shell

sw

sandbox copy SB [--name NAME]

Makes a new sandbox holding what SB's apps hold now, as its version 1, in the same mode (a blank sandbox makes a blank copy). Not SB's earlier versions, tests or runs. Prints the copy's id, and its name, mode and version on stderr. Without --name the copy is called <name> copy . See Rename or copy a sandbox .

Shell

sw

sandbox copy p-7d21c4

--name

"Acme refunds"

# p-3e81a0

Generated companies

sw env makes a new sandbox and generates a made-up company into it in one step. It also lists and shows sandboxes, by the name they had before (environments). See Fill a sandbox .

sw env new

Shell

sw

env new

--apps

APP,APP

--describe

TEXT [--company NAME] [--people N] [--weeks N] [--templates] [--no-wait]

Option Description
--apps Required. Comma-separated app names, as for sw sandbox new .
--describe Required. The company and what the agent will be tested on.
--company The company's name; the first 80 characters are kept.
--people Employees, 2 to 5,000.
--weeks Weeks of history, 1 to 104.
--templates Write the text from built-in templates, without Claude: quicker, plainer.
--no-wait Print the new sandbox's id and return while it generates.

Prints the new sandbox's id, then follows the generation as sw sandbox generate does. Exits 0 when it ends ready or partial .

sw env ls

Every sandbox, newest first: id, status, apps and title.

sw env show

Shell

sw

env show SB

The sandbox's id, title and status (with the error, if it failed), and per app whether it is up and what it holds.

Tasks and tests

A task is a folder in Harbor's layout: instruction.md , task.toml , tests/checks.json , optionally tests/verify.py and solution/solve.py . A test is a task kept in your workspace; its id is t-… . Importing a task is the only way to add a test. See Tasks and Upload a task .

sw task import

Shell

sw

task import PATH [--sandbox SB] [--check]

Sends a task you wrote, its folder or a .zip of it, to a sandbox. The workspace proves it on fresh copies of the sandbox's latest version (doing nothing must fail; a reference solution, when there is one, must pass) and keeps it as a test once every proof passes. --check proves it and keeps nothing.

Option Description
PATH The task's folder, or a .zip of it.
--sandbox The sandbox. Default: stateweave_sandbox under [metadata] in task.toml .
--check Only prove it.

Only instruction.md , task.toml and the files under tests/ and solution/ are sent; environment/ , hidden files and caches are not. The files must be UTF-8 text, 1 MB at most in all. It prints one line per proof ( ✓ or ✗ , a failed one with what it found), then the new test's id, or that nothing was kept. Exits 1 when the task cannot be read or a proof fails.

Hosted workspaces. For now a hosted workspace refuses a task that has tests/verify.py or solution/solve.py , with or without --check . Judge it with tests/checks.json alone.

Shell

sw

task import ./tasks/refund-reply

--check

sw

task import ./tasks/refund-reply

--sandbox

p-7d21c4

sw task ls

Shell

sw

task ls [--env SB]

The tests you can run, every sandbox's or one's, one per line: id, kind ( answer or action ), apps and title. The id comes first, for scripts.

sw task faults

Shell

sw

task faults SB [--targets [--app APP]]

The fault presets the sandbox's tests may inject: id, title, and whether it was seen live on the real service or carried over from another app's (printed as carried over (未验证) , "not verified"). A task names them in its task.toml ; see Faults in a task .

With --targets , where faults can be pinned instead: per app (or only --app 's), each endpoint's id (what stateweave_pinned_faults ' endpoint takes), its label and the kinds it can meet, then what each kind does and the defaults of random faults.

Output (shortened)

slack (Slack) … chat.postMessage /api/chat.postMessage outage,transient_auth,rate_limited,hang,error_after_commit,hang_after_commit conversations.history /api/conversations.history outage,transient_auth,rate_limited,hang,drop … kinds: outage Every request fails for a while … random faults (stateweave_random_faults) default to {"rate": 0.05, "max": 5, "max_hang": 1, "max_outage": 1}

sw task recheck

Shell

sw

task recheck SB [TEST …]

Re-checks, in the background, the sandbox's tests that need it because their data changed (all of them, or the ones named), and prints their ids. A test is not run again until its re-check passes.

Runs

sw run

Shell

sw

run TEST

--agent

LABEL [--env SB] [--timeout SECONDS] [--transcript-format F] [--json] -- COMMAND …

sw

run SB

--agent

LABEL [--prompt TEXT] [--checks FILE] [--answer-format JSON] [--apps A,B] [--persona HANDLE] [--timeout SECONDS] [--transcript-format F] [--json] -- COMMAND …

With a test's id ( t-… ), it starts a graded run of the test, runs COMMAND (your agent, in any language) with the run in environment variables, then hands in the answer when the command exits, whatever its exit code, and prints the result. Ctrl-C gives the run up instead. A command that cannot be found is refused before a run starts.

With a sandbox's id ( p-… ), it opens a twin run instead: fresh copies of the sandbox's latest version, with no test and no faults. COMMAND runs on them with the request you give, --checks judges what it left, and the copies stop when it is done. Nothing is graded or kept as a test; the run's page keeps every call.

Option Description
--agent Required. The label runs are compared by, up to 80 characters, e.g. my-agent@0.3 .
--env The sandbox, when the test id is in several.
--timeout Seconds before the run ends unfinished: 60 to 86,400. Default 1,800.
--transcript-format What your agent writes to STATEWEAVE_TRANSCRIPT_FILE , e.g. claude-code-stream-json . Default: guessed, jsonl , json or text .
--json Print the result as JSON, with agent_exit , your command's exit code.

For a sandbox (twins) only:

Option Description
--prompt The request, as STATEWEAVE_PROMPT .
--checks A task's tests/checks.json , or the task's folder: the checks judge what your agent left and its answer, as a graded run of the task would.
--answer-format The answer's shape, with placeholder values. Your agent is then asked to answer ( STATEWEAVE_KIND=answer ); otherwise the kind is action .
--apps Only these of the sandbox's apps, comma-separated.
--persona The handle of the person whose credentials your agent gets.
--timeout Seconds the copies stay up at most: 60 to 86,400. Default 3,600.

It prints the run's page to standard error when the copies open, then passed , failed (with --checks ) or done , the number of calls and the page; per app the calls and the records added, changed and removed; the answer; and each check with ✓ or ✗ and what it found. When no call reached the apps it says so: your agent may still be pointed at the real service. It exits 0 when every check held, or, without --checks , when your command exited 0.

Shell

sw

run p-7d21c4

--agent

my-agent@dev

--prompt

"$(cat kickoff/instruction.md)"

--checks

kickoff -- ./stateweave-agent.sh

Output

sw: twins r-5b0c1d2e of p-7d21c4 opened: https://acme.app.stateweave.net/\#/runs/r-5b0c1d2e passed 2 calls https://acme.app.stateweave.net/\#/runs/r-5b0c1d2e slack 2 calls 1 added ✓ posted once ✓ it is in #general

COMMAND gets these variables, for a test and for twins alike:

Variable Value
STATEWEAVE_RUN The run's id, r-… .
STATEWEAVE_PROMPT What to ask your agent.
STATEWEAVE_KIND answer (it finds something out) or action (it changes the apps).
STATEWEAVE_ANSWER_FORMAT For an answer test, the shape of the JSON value to answer with.
STATEWEAVE_RUN_FILE A file holding the whole run as JSON: per app its base_url , endpoints , credentials and mcp server.
STATEWEAVE_MCP_CONFIG A file holding {"mcpServers": {…}} , as Claude Code's --mcp-config takes it.
STATEWEAVE_<APP>_URL , STATEWEAVE_<APP>_MCP_URL , STATEWEAVE_<APP>_<KIND>_TOKEN Each app's address, its MCP server and the persona's tokens, such as STATEWEAVE_SLACK_URL and STATEWEAVE_SLACK_BOT_TOKEN : see Apps and credentials .
STATEWEAVE_ANSWER_FILE Where to write the answer: JSON, or plain text, which is handed in as a string. Write nothing for an action test.
STATEWEAVE_TRANSCRIPT_FILE Where your agent may write its own record of the run (messages, tool calls). Handed in after grading when it is not empty, up to 20 MB; a transcript the workspace refuses is reported and does not change the result.

Shell

sw

run t-bde537

--agent

my-agent@0.3 -- python agent.py

It prints the run's page to standard error when it starts, then a line with the status, the number of calls and the page, the reasons below it, and your command's exit code when it was not 0. The run's meta holds the command (its first 200 characters). See Run your agent .

sw worker

Shell

sw

worker

--agent

LABEL [--timeout SECONDS] [--transcript-format F] [--once] [--json] -- COMMAND …

Waits for runs queued for a worker, such as Run again on a run's page or a workflow's run, and drives each one as sw run does, labelled LABEL , until Ctrl-C. COMMAND starts afresh for every run, so a change to your agent counts from the next run on.

Option Description
--agent Required. The label its runs get.
--timeout Seconds each run may take, 60 to 86,400. Default: the time limit of the run being repeated.
--once Drive one run, then exit with its result.
--transcript-format , --json As for sw run .

Each run shows the command, this machine's name and, in a git checkout, the commit it runs at (with + uncommitted changes when there are some). When the workspace cannot be reached, the worker keeps asking every 5 seconds. A run that was cancelled or timed out while your agent worked is reported and skipped.

sw trace

Shell

sw

trace RUN [--dir DIR] [--attempt N]

Writes a run's whole record into DIR , by default .stateweave/runs/RUN/ , for whoever judges it: trace.jsonl (every call your agent made, bodies whole, numbered by attempt), changes.json (per app how many records were added, changed and removed), task.json (the request, persona, answer format, the answer and the verdict), faults.json (the injected faults that acted) and transcript.* when one was handed in. The folder gets a .gitignore of * . --attempt keeps only that attempt's calls. It prints where it wrote, the calls per app (and how many failed) and the run's page.

Coding agents

sw setup

Shell

sw

setup [--client claude-code|codex|cursor|all] [--project] [--remove]

Gives Claude Code, Codex and Cursor two skills, stateweave-setup (connect your agent) and stateweave-use (sandboxes, tasks, faults, runs), so they work with StateWeave through sw . It doesn't ask: it says what it did. See From your coding agent .

Option Description
--client claude-code , codex , cursor or all ; repeatable or comma-separated. Default: the ones found on this machine (the command on the PATH, or its folder in your home).
--project This project's .claude/skills/ and .agents/skills/ instead of your own, to commit.
--remove Take the skills out again. Default: every client.
Client Skills
Claude Code ~/.claude/skills/ , or .claude/skills/
Codex ~/.agents/skills/ , or .agents/skills/
Cursor ~/.agents/skills/ , or .agents/skills/

For Claude Code it adds *.app.stateweave.net to sandbox.network.allowedDomains in ~/.claude/settings.json (with --project , .claude/settings.json ), beside what is there, so sw and your agent reach your workspace from inside Claude Code's sandbox, and prints Allowed Claude Code's sandbox to reach *.app.stateweave.net . A settings file that is not valid JSON is left alone, with a note. --remove takes the entry out again.

It also takes out what sw mcp install (0.4 and 0.5) added: the stateweave MCP server entries that start stateweave mcp serve , in Claude Code ( claude mcp remove -s user stateweave , or .mcp.json ), Codex's config.toml and Cursor's mcp.json , and the older stateweave and stateweave-task skills. A skill folder or server entry it didn't write is left alone and reported. sw mcp install , uninstall and serve are gone: they say to run sw setup .

sw mcp config

Shell

sw

mcp config RUN

Prints a running run's MCP servers as {"mcpServers": {…}} , the format of Claude Code's --mcp-config . Exits 1 once the run has ended. sw mcp-config RUN is the same command.

Shell

sw

mcp config r-19dc0cec > mcp.json

claude

-p

"…"

--mcp-config

mcp.json

Low-level run commands

For harnesses that drive a run one step at a time.

Command Description
sw tests [--env SB] The tests you can run, as sw task ls prints them.
sw start TEST --agent LABEL [--env SB] [--timeout SECONDS] Starts a run and prints it as JSON: the request, the persona and each app's address, credentials and MCP server.
sw finish RUN [--answer JSON] [--transcript FILE] [--transcript-format F] Hands in the answer (JSON; leave it out for an action test), and the transcript with it, and prints the result as JSON. Exits 0 whether the run passed or not.
sw cancel RUN Gives the run up and prints its result as JSON.

sw tests and sw start also take --project , the old name of --env .

Exit codes

Code Meaning
0 Done. For sw run and sw worker --once : the run passed.
1 The run did not pass, a generation failed, no test was kept, the workspace could not be reached, or it refused the request. sw says why on standard error, with the HTTP status and each problem on a line of its own.
2 The command line itself is wrong.
130 Stopped with Ctrl-C.

Apps and credentials

Python

Sandboxes

Fill a sandbox

Starter

Apps and credentials

the API

sw env new

Rename or copy a sandbox

Tasks

Upload a task

Faults in a task

twin run

Run your agent

From your coding agent