CLI

Use @01.software/cli when an operator or coding agent can run shell commands. Human CLI commands are interactive and operator-facing. The 01 agent namespace is a separate JSON protocol for coding agents; do not mix their output or exit contracts.

Choose A CLI Surface

Install the public package with the package manager used for your shell environment, then inspect the shipped help:

npm install --global @01.software/cli
01 --help
01 agent --help

Human operators can run 01 login and 01 tenant use <name>. Automated agents should prefer SOFTWARE_PUBLISHABLE_KEY plus SOFTWARE_SECRET_KEY from trusted environment storage. Never put a real token in command arguments, source files, logs, or chat.

Configure An Embedded Admin App

Tenant admins use the Human CLI to manage the active tenant's single embedded app binding. This control-plane action requires the user PAT obtained by 01 login; tenant API keys (sk01_) are rejected.

01 tenant use acme
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace \
  --dry-run
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace
01 embedded-app show
01 embedded-app disable

--dry-run validates locally and performs no write. The origin must be one exact HTTPS origin and the path must be relative without a query or fragment. These commands are operator-facing and are not part of the 01 agent machine-stable manifest.

Diagnose A Local App Integration

Run the redacted diagnostic from an app directory after configuring its SDK environment:

01 doctor
01 doctor --app-env-file .env.local
01 doctor --origin https://app.example.com
01 --format json doctor
01 --format ndjson doctor

01 doctor defaults to localized human output; explicit json and ndjson formats are for machine consumers. For Next.js/CRA it reads .env, .env.development, .env.local, then .env.development.local; for Vite it reads .env, .env.local, .env.development, then .env.development.local. Other apps use only .env then .env.local, or one explicit regular --app-env-file. It validates one app publishable/secret pair, resolves the SDK API target from those files only, and probes SDK tenant context. It never falls back to CLI PAT credentials, prints a credential value or raw response body, mutates state, or runs project scripts. --origin performs an uncredentialed CORS OPTIONS diagnostic and does not send Authorization or a secret. The origin must be an absolute http(s) URL. A 403 is denied even when it carries ACAO; successful responses need matching ACAO. 404, 408, 429, 5xx, and network failures are inconclusive rather than a CORS conclusion.

01 agent doctor returns exactly one JSON value. A completed diagnostic exits with Agent success (0) even when its payload reports blocked or attention; an invalid explicit app-env-file or origin is Agent INVALID_INPUT (exit 2).

Discover The Agent Contract

Start every Agent CLI integration with the manifest instead of scraping help text:

01 agent manifest --pretty
01 agent context --counts --pretty
01 agent schema articles --pretty

The version 1 manifest lists the current server-auth collections and their supported operations. context reports the active tenant, features, active collections, and field configuration. schema returns the tenant-effective field contract. Schema writable metadata is advisory; server access control and the manifest's reviewed plan operations remain authoritative.

For customers and products, schema may also return optional collection.customFields with storagePath: "customData". Each active definition contains its machine key and type, optional required: true, and select option storage values. Display labels, help text, internal ids, and tenant metadata are omitted. This structural discovery does not grant access to stored customData values or add write operations.

Query And Get

All manifest collections support query and get. Keep agent context small with filters, pagination, sorting, and field selection:

01 agent query articles \
  --where '{"status":{"equals":"published"}}' \
  --limit 10 \
  --sort=-updatedAt \
  --select=id,title,updatedAt

01 agent get articles art_123 --select=id,title,updatedAt --pretty

query returns the paginated Payload shape; get returns one bare document. --limit and --page accept positive decimal integers only.

Plan And Confirm Content Changes

Agent writes are deliberately two-step. plan validates input and stores an expiring local plan without changing remote data. Review its JSON, then run the returned confirmCommand with the exact token and hash:

printf '%s\n' '{"title":"Release notes","status":"draft"}' | \
  01 agent plan create articles --data-stdin --pretty

01 agent confirm <planToken> --hash <planHash> --pretty

Mutation payloads are accepted through --data-stdin or --data-file only. The manifest currently advertises create/update/delete plans for articles and article categories/tags, links and link categories/tags, plus canvases, canvas-categories, and canvas-tags. documents, document-categories, and document-types advertise create/update but not delete. The canvas-node-types and canvas-edge-types catalogs remain read-only through the Agent CLI. Do not infer write support from schema fields.

Plans expire after 15 minutes by default, bind to the current auth/API context, and reject stale update/delete targets. If the remote mutation fails, the plan returns to pending so the caller can retry confirm with the same token and hash while the plan is valid. After the mutation succeeds, the claimed or consumed plan must not be replayed. Human CLI --dry-run is a different operator workflow, not the Agent plan contract.

Product Detail And Commerce

The Agent namespace provides a shaped product read in addition to generic collection reads:

01 agent product detail \
  --slug canvas-bag \
  --market kr \
  --locale en \
  --fallback-locale ko \
  --pretty

Use exactly one of --slug or --id. Unavailable products return a successful discriminated result such as {"found":false,"reason":"not_published"}.

The Agent namespace does not currently provide commerce mutation commands. Use the existing Human CLI domain commands shown by 01 order --help, 01 cart --help, 01 checkout --help, 01 payment-session --help, and related groups when an operator-facing command fits; use the server SDK for application or automated commerce mutations. Do not treat Human CLI text/output or exit codes as the Agent JSON contract.

Cart capability operations, Checkout creation, and PaymentSession creation/cancellation/confirmation accept sensitive JSON only through --data-stdin or --data-file. Interactive stdin is rejected, and each input is limited to 1 MiB. Successful --dry-run output confirms only the action and validity; it never echoes payload values. This keeps Cart/Checkout capabilities, customer snapshots, idempotency keys, and provider authorization material out of shell history, process listings, and logs. Keep input files access-restricted and remove them after use. 01 cart create is the exception: it accepts no input and uses canonical defaults because the request contains no capability; use a sensitive input source only when supplying optional market or attributes.

Output, Errors, And Retries

Agent success and normal errors each emit exactly one JSON value on stdout. Add --pretty for two-space-indented success JSON. Add --output-file <path> to write the complete success result to a secure file and receive a compact stdout receipt containing outputFile and bytes:

01 agent query articles --limit 100 --output-file ./articles.json

On POSIX, the result file uses mode 0600; unsafe targets such as symlinks, directories, and multiply linked files are rejected.

Normal error envelopes include error.code, error.message, and error.retryable. Retry only when retryable is true, honor retryAfter when present, and preserve operation idempotency. The CLI does not retry on behalf of the caller. Validation, auth, not-found, plan, and monthly quota errors are terminal; network/timeouts, HTTP 503, transient rate limits, and explicitly unavailable providers may be retryable.

Next Actions

• Need credential boundaries: open Authentication & Keys.
• Need typed application code or commerce mutations: open SDK.
• Need a direct HTTP escape hatch: open API.
• Need hosted, shell-less discovery: open MCP.