Skip to main content

​
Turn off prompts

When stdin and stdout are a terminal, the CLI prompts for missing required flags and opens an explorer when you run continuous with no command. Pass --no-interactive in scripts so the CLI never prompts, even from a terminal:
Without a terminal the CLI never prompts. continuous explore then exits with an error, and continuous with no command prints help.

​
Read values in a script

jq is optional. Use it when a script needs raw values from a JSON response. For example, print one Simulator ID per line:
For curl scripts, -fsS hides the progress meter and reports failed HTTP requests. These flags are optional when you run a request by hand.

​
Send a request body

Commands with a JSON body, including create, fork, token minting, World build/start, and clock advances, take individual flags, a --body JSON string, or JSON on stdin. Flags override values from --body or stdin. --body wins over stdin. These commands read stdin to end-of-file whenever stdin is not a terminal, even when the flags already supply the body. In a pipeline or a job that leaves stdin open, the command waits until stdin closes. Redirect from /dev/null or pass --body when nothing is meant to arrive on stdin:
simulators build is different: it sends multipart form data. Pass the build request with --request and the OpenAPI or WSDL file with --spec:

​
Preview a request

--dry-run prints the method, URL, headers, and body to stderr and skips the network call. The Authorization header is redacted.
Do not use the exit status of a dry run in scripts; see Known issues. --debug logs the real request and response to stderr. When you pass both flags, only the dry run runs.

​
Agent mode

Agent mode turns off color, prompts, and the explorer, defaults output to TOON, prints errors as JSON on stderr, and refuses the interactive configure and auth login commands. continuous explore prints help instead. The CLI enables it when one of these variables is set to 1, true, or yes: CLAUDE_CODE, CURSOR_AGENT, CODEX, AIDER, CLINE, WINDSURF_AGENT, GITHUB_COPILOT, AMAZON_Q, GEMINI_CODE_ASSIST, SRC_CODY, FORCE_AGENT_MODE. To force it in a script, set FORCE_AGENT_MODE=1. To turn it off, unset those variables or set them to 0. The --agent-mode flag does not work in the current release; see Known issues.

​
Errors and exit codes

Any failure exits with status 1. API errors are printed on stderr. With --output-format json or --jq, and in agent mode, stderr carries a JSON object followed by one plain line that repeats the API’s problem body, so parse the object rather than the whole stream. The object’s error field holds the problem body as a JSON string; in agent mode the object also carries error_type, message, and hints. Parse error and read its code; see Known issues for why error_type is not reliable.

​
Known issues

These reproduce on v0.1.18.
  • --agent-mode and --agent-mode=false are accepted but ignored. Use the environment variables in Agent mode.
  • --dry-run prints the preview and then exits with status 1 for simulations create, simulations fork, simulators build, worlds build, and every delete command. It exits 0 for list, get, start, stop, cancel-*, and mint-simulation-token.
  • In the default pretty format, an API error message prints twice. In json, --jq, and agent modes the JSON object is followed by one plain line with the problem body.
  • The CLI cannot read the HTTP status from API errors, so error_type for a rejected key is connection_error. Read the code inside error instead.
  • --output-format yaml drops the underscores from keys (next_cursor prints as nextcursor) unless --include-headers is also set; use json if you do not want the headers.