How to use the CLI

Install the standards CLI, log in to the hosted API, and script your workspace with JSON, table or CSV output.

The standards CLI (@stndrds/cli) talks to the Standards API over HTTP. It is the shortest path from a terminal to your records, documents, schema and MCP servers.

Install and log in

npm i -g @stndrds/cli

Save an instance profile, then select it. Omit --key to be prompted for it.

standards login --url https://api.standards.new/v1 --name prod --key stndrds_your_api_key

Always pass --url for the hosted API

The compiled default URL is http://localhost:4100/v1. Without --url, login stores a profile that points at a local server and every command answers with a connection error.

login validates the key against the API before it saves anything. Confirm the profile is usable:

standards auth whoami

Profiles

Profiles live in ~/.standards/config.json, written with mode 0600. Set STANDARDS_CONFIG_DIR to move the whole directory, for example in CI.

standards instances

standards use prod

standards current

standards logout prod

logout without a name removes the active profile.

STANDARDS_API_URL and STANDARDS_API_KEY form a profile of their own. standards instances lists it as sandbox with source: "env". It is active only while no profile is selected in the config file.

STANDARDS_API_URL=https://api.standards.new/v1 STANDARDS_API_KEY=stndrds_ci_key standards records list contacts

Resolution order

--api-url or --api-key on the command line. Either flag bypasses every profile; the other value falls back to the environment, then to the compiled default.
--instance <name>, then the profile selected with use.
STANDARDS_API_URL / STANDARDS_API_KEY.
The compiled default URL, with no key.

Global flags

Flag	Description
`--format <fmt>`	`json` (default), `table` or `csv`.
`--api-url <url>`	API base URL. Bypasses the profile.
`--api-key <key>`	API key. Bypasses the profile.
`--instance <name>`	Use a named profile for this call.
`--tenant <id>`	The tenant you are authenticated in. A confirmation of intent, not a selector: the API refuses any other value.

Output formats

json prints the response as-is. table and csv read the first row's keys as columns; a scalar or object response becomes a one-row table. Nested values are serialised as JSON. Table cells are truncated at 50 characters.

standards keys list --format table

records list and records search return { data, page }, so the table shows two columns. Pipe the JSON through jq instead:

standards records list contacts --limit 20 | jq .data

Exit codes

Code	Meaning
`0`	Success. For `diff`, no differences.
`1`	The API refused the request or the command failed. The message reads `✗ Error (status): message`, for example `✗ Error (404): Record not found`.
`2`	No instance is configured: no profile, no `--api-key`, no `STANDARDS_API_KEY`. `pull` and `diff` also exit with code 2 on transport or schema errors.

diff uses exit code 1 to report differences, not a failure. See Schema and sources.

Every command except login, use, instances, current, logout and help needs a key. Without one the CLI prints ✗ Error: No Standards instance configured and stops with exit code 2.

API keys

standards keys list

standards keys create --name ci-bot --expires 2026-12-31 --yes

standards keys revoke <keyId> --yes

create and revoke refuse to run without --yes. A CLI-created key inherits your key's roles, see Workspaces and API keys.

Shell pitfalls

Single-quote JSON so the shell keeps the double quotes: --data '{"name":"Alice"}'.
--filter takes the raw filter tree as JSON, exactly as the API expects it.
--sort takes one rule, attribute:direction. Pass it once.
--fields "" hydrates no reference attribute. Omit the flag to hydrate all of them.
Wrap --query in quotes when it contains spaces.

Next steps

Records: list, search, create, update and attach a file.
Documents and files: manage packs and read OCR text.
Schema and sources: inspect the deployed schema and its sources.
MCP servers: connect outbound servers from a terminal.