sw command line

sw drives StateWeave from a shell: scenarios, data, tests and runs of your agent. It comes with pip install stateweave-sdk; python -m stateweave is the same command.

sw --help
sw run --help       # every command has its own

#Configuration

Each command needs your workspace's address and an API key. The first of these that is set wins:

1. STATEWEAVE_URL and STATEWEAVE_API_KEY in the environment.
2. What sw login kept in ~/.config/stateweave/config.json (or $XDG_CONFIG_HOME/stateweave/config.json, or the file STATEWEAVE_CONFIG names), readable only by you.

With no address set anywhere, sw uses http://127.0.0.1:8700, a studio running on your own machine.

#Exit codes

#Signing in

#sw login

sw login [--url URL] [--key sw_…]

Checks the key with the workspace, then keeps the address and key. Without --key it asks for it without echoing. Nothing is kept if the workspace refuses the key.

#sw whoami

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

#sw logout

Forgets the kept address and key.

#Scenarios

#sw env ls

Every scenario: id, status, apps and title.

#sw env show

sw env show ENV

A scenario's status, and per app whether it is up and what it holds.

#sw env new

sw env new --apps APP,APP --describe "…" [--company NAME] [--people N] [--weeks N] [--templates] [--no-wait]

Exits 0 when the scenario ends ready or partial.

#Data

#sw data kinds

sw data kinds ENV

What each app of the scenario takes, field by field, with what each field accepts.

#sw data add

sw data add ENV APP KIND --FIELD VALUE [--FIELD VALUE …]
sw data add ENV APP KIND --file items.json

Adds one item from flags, or the items in a JSON file (a list, or one object). A field's _ may be written -. --FIELD-file PATH reads the value from a file. List fields take comma-separated values or JSON; object fields take JSON. See Your own data.

#Tests

#sw task ls

sw task ls [--env ENV]

The tests you can run: id, kind, apps and title. The id is the first column, for scripts.

#sw task new

sw task new ENV --request "…" [--criteria "…"]
sw task new ENV --request "…" --request "…"
sw task new ENV --file requests.txt
sw task new ENV --suggest N [--focus "…"] [--hard]

Follows the job and prints each test it kept, and each request it rejected with why and a rewording. Exits 0 when at least one test was kept.

#sw task faults

sw task faults ENV

The fault presets the scenario's tests may inject, each marked seen live or carried over (未验证). See Faults.

#sw task recheck

sw task recheck ENV [TASK …]

Re-checks the tests whose data changed (all of the scenario's, or the ones named).

#Runs

#sw run

sw run TASK --agent LABEL [--env ENV] [--timeout SECONDS] [--json] -- COMMAND …

Starts a run of TASK, runs COMMAND with the run in its environment, hands in the answer when it exits (whatever its exit code), and prints the result. Ctrl-C gives the run up. See Connect your agent for the variables COMMAND gets.

#sw worker

sw worker --agent LABEL [--timeout SECONDS] [--once] [--json] -- COMMAND …

Waits for runs someone asks for with Run again on a run's page, and drives each as sw run does, until Ctrl-C. COMMAND starts afresh for every run. --once drives one run and exits with its result. --timeout defaults to the time limit of the run being repeated. See Run again.

#sw mcp-config

sw mcp-config RUN

Prints a running run's MCP servers as {"mcpServers": {…}}, the format of Claude Code's --mcp-config.

#Low-level run commands

For harnesses that drive runs one call at a time. Each prints JSON.