CLI

npm install -g @substrio/cli

Run it once without installing with npx @substrio/cli <command>.

Sign in and profiles

Save a key once and every later command reuses it:

substrio login --url https://acme.example.com --key - --tenant acme < app.key

--key - reads the key from stdin, never from argv or shell history. Without --url, login saves a profile for the hosted platform, https://mcp.substrio.com. The profile is saved to ~/.substrio/config.toml (owner-only, mode 0600); set SUBSTRIO_CONFIG_DIR to move it. --profile NAME saves under a name other than the default; the default changes only with --default, or when there is none yet. login --list shows saved profiles, login --remove NAME deletes one. login --offline ... --tenant SLUG saves a profile with no round trip to the server, marked unchecked until a later login without --offline confirms it.

An agent given a one-time connect code (substrio_ae_..., made by POST /v1/_accounts/{id}/agent/enrollments; the console connects agents over MCP with OAuth and makes no codes) redeems it with:

substrio connect - < code.txt          # or: substrio connect substrio_ae_...

The command sends one POST /v1/_agent/exchange request to https://mcp.substrio.com unless --url specifies another server. The session acts as the code's owner and is saved as profile agent in the owner-only file. Use --profile NAME for another name or --default to make it the default. The command prints the MCP setup. It does not print the code or secret unless --show is used; then stdout contains only the secret for $(...) in an MCP client setup command. See agent-sessions.md. A spent or expired code exits with AGENT_CODE_INVALID.

Check what is in effect, and where each value came from, with:

substrio whoami

Each run resolves the server URL, key, and app in this order, highest priority first:

1. Environment variables: SUBSTRIO_URL, SUBSTRIO_TENANT (also set by the --tenant flag), and SUBSTRIO_MASTER_KEY.
2. substrio.toml in the current directory (the project file substrio init writes).
3. The saved profile named by SUBSTRIO_PROFILE, --profile, or profile in substrio.toml.
4. The profiles file's default_profile.

Use a saved profile to keep credentials out of project files and shell history.

Global flags

Global flags are parsed wherever they appear on the command line and removed before the command receives its arguments:

A destructive command returns exit code 9 when it has no --yes and cannot prompt on a terminal. This includes runs under --json.

Calling any operation

Call any operation the server exposes, including one without a dedicated subcommand, with:

substrio op NAME key=value key2=value2

For example:

substrio op collection.create name=orders
substrio op data.insert collection=orders data='{"total": 42}'

• key=value sets one field; dotted keys nest (data.total=42 sets data: {total: 42}). A value that parses as JSON (a number, true, false, null, a quoted string, an array or object) is sent as that type; anything else is sent as a string.
• --data '{...}' sends a whole JSON body instead of (or in addition to) key=value fields.
• --file PATH reads the body from a file (- for stdin).
• Route path parameters ({id} in the operation's route) come from positional arguments, in order, before any key=value.

substrio op prints the operation's JSON result. substrio call is the same command under another name.

JSON output

Pass --json on any command to get machine-readable output instead of the human-readable default:

substrio op collection.list --json

Results are JSON on stdout. Errors are JSON objects on stderr with error, code, and detail when supplied by the server. A command that streams records, such as substrio data import or substrio logs --follow, writes one JSON object per line (NDJSON) under --json.

Exit codes

Script against these codes instead of parsing error text: substrio op data.get collection=orders id=1 --json || exit $? exits 4 when the order does not exist, 3 when the key is refused.

Command reference

Commands listed by substrio --help are grouped by section. Run substrio COMMAND --help for help with a command.

Start

Apps

Ship

History

Any operation

Registry groups