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_..., from the console's Agents page) redeems it with:

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

One request, POST /v1/_agent/exchange, against https://mcp.substrio.com unless --url names another server. The session acts as the code's owner; it is saved as profile agent (--profile NAME for another, --default to make it the default) in the same owner-only file, and the MCP setup is printed. Neither the code nor the secret is printed, except with --show: stdout then holds the secret alone, for $(...) in an MCP client's setup command (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, the key and the app in this order, highest priority first:

1. Environment variables: SUBSTRIO_URL and SUBSTRIO_TENANT (also set by the --tenant flag). The key always comes from a saved profile.
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.

Global flags

These are parsed wherever they appear on the command line, and removed before the command sees its own arguments:

A destructive command with no --yes and no terminal to ask on (including any run under --json) refuses with exit code 9.

Calling any operation

Every operation the server exposes, including ones with no dedicated subcommand, runs 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

Every result is JSON on stdout; every error is a JSON object on stderr with error, code and, where the server sent one, detail. A command that streams records (substrio data import, 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

Every command substrio --help lists, by section. Run substrio COMMAND --help for one command.

Start

Apps

Ship

History

Any operation

Registry groups