Join early access

The CLI

torno is the priority agent interface, and the fastest one for humans who live in a terminal. It is non-interactive by default, machine-readable, and calls the same versioned API and policy paths as the web app — there is no privileged side door.

Global contract

Every command inherits the same flags:

Flag Purpose
--json Structured output on stdout; progress text never mixes into it
--yes Explicit confirmation for destructive commands in automation
--dry-run Plan without applying; a dry run never mutates
--api-url, --api-key Target and credential overrides
--workspace, --property, --env Explicit context, serialized once into the request
--reasoning The required agent rationale, stored as a claim

Mutations accept structured --input files or stdin, and carry idempotency keys where applicable. Confirmation is always explicit — a command never hangs waiting for a human who is not there.

Command families

  • Identity and context: login, logout, whoami, env, key, docs.
  • The Loop chain: loop, signal, analyzer, insight, hypothesis, change, experiment, metric, revenue, ads, context, approve.
  • Data and operations: events, cohort, customer, analytics, listening, privacy, notifications.
  • Code and integration: init, config pull|diff|push|validate, tag scan|check, events check, webhook, stream, stella.
  • Escape hatch: rpc <capability> invokes any binding in the capability map, and mcp serve exposes the generated stdio MCP server.

Curated commands own the friendly workflows; generated rpc provides breadth when a curated command would add nothing. See The agent interface for how the capability map keeps all surfaces in step.

# Identify the caller, its scopes, and the active context
torno whoami --json

# Read the current Loop state before an agent takes a turn
torno context --property demo-app --json

# Propose a Hypothesis from structured input, with required reasoning
torno hypothesis create --input hypothesis.json \
  --reasoning "Signup drop-off is concentrated on the plan-selection step" \
  --json

Exit codes agents can branch on

Exit codes distinguish success, validation errors, authentication failure, scope or policy denial, pending approval, rate limiting, transport and server faults, and data-freshness conditions. Pending approval gets its own code because it is not an error: the request was accepted and is waiting for a human, as described in Policy and approvals. Paired with --json, an agent can decide whether to fix its input, wait, escalate, or stop — without parsing prose.

Help and torno docs --agent work offline, with no credentials and no network.

Authentication and storage

Agents authenticate with an API key, from TORNO_API_KEY or --api-key. Humans run torno login, a device-authorization flow: the CLI prints a code and a URL, you confirm in the browser, and the session is stored for refresh. Missing credentials produce an instruction, not a stack trace.

Honest note: human login sessions are stored in a config file at ~/.config/torno/config.json with mode 0600 — readable only by your user, but a file, not the OS keychain. Keychain storage is not implemented yet. Treat that file like a credential, and prefer narrowly scoped API keys for automation.

For putting the CLI to work in CI, start with Loops as code; for the first-run experience, see Getting started.