CLI command reference

Every command, flag and exit code in the published looot CLI (npm looot 1.1.0), plus env vars and the config file.

looot is published on npm as looot, currently version 1.1.0. Install it with npm install -g looot@1.1.0 (see Install); looot doctor checks the Node version and compares your installed version against the one published on npm.

looot <command> [options]

looot help prints a short summary. looot help --all prints every command with all its flags. looot help <command> details one command.

Output

On a terminal, output is a short human summary by default. Piped or redirected, it’s JSON. Add --format json, --format jsonl or --format human after the command to choose explicitly either way; --format only works right after the command. jsonl splits a top-level array result into one JSON object per line; it is not network streaming, and every other result stays one line. Human output redacts secret-looking fields.

Env and config

--url beats LOOOT_API_URL beats the saved ~/.config/looot/config.json beats https://api.looot.ai. LOOOT_TOKEN beats the saved login. There is no --token flag: a secret never sits in argv or shell history, so use looot login or set LOOOT_TOKEN.

looot login saves the token to ~/.config/looot/config.json, readable only by you.

Exit codes

Commands

login

looot login [--token-stdin]

Opens https://looot.ai/cli/approve in your browser with a code, waits up to 10 minutes for you to approve it there, and saves the credential. The raw token never appears in the URL. --token-stdin instead reads a token from stdin (opening /connect and verifying it once, no polling): echo "$TOKEN" | looot login --token-stdin.

logout

looot logout

Revokes the saved token on the server, then deletes the local config file either way. A failed revoke leaves the token valid until it expires or is revoked in Settings. Only the token login saved is revoked, never a LOOOT_TOKEN from the environment (which may be shared with CI).

whoami

looot whoami

Prints the organization, role and granted scopes for the signed-in token, plus its last 4 characters only.

token

looot token --reveal

Prints the saved (or resolved) token to stdout, for a script: export LOOOT_TOKEN="$(looot token --reveal)". Without --reveal it refuses, on a terminal and in a pipe alike, since an agent’s shell is always a pipe. With --reveal it warns on stderr that the token itself is on stdout. The older --yes-print flag still works.

init

looot init [--yes] [--dry-run] [--embed] [--project]

Logs in if needed, detects Claude Code, Cursor and Codex, and offers to write the looot MCP entry into each one it finds: a credential reference by default (--embed writes the token itself into the file instead), then prints two commands to try and your balance. --yes skips the per-client confirmation prompt. --dry-run asks nothing, logs in to nothing, calls nothing, writes nothing, and only prints the looot entry it would have written. --project writes to the project-local agent config; without it, init writes the user-level one.

doctor

looot doctor [--project]

Checks the Node version, gateway reachability, token validity, clock skew, which agent clients it detects, and this install’s version against the one published on npm.

search

looot search "text" [--limit N] [--provider ID] [--category ID]

A human table of matching endpoints: id, provider, price per call. An alias for catalog search --query "text". Works signed out, reading the public catalog; see Browse without an account.

inspect

looot inspect <endpoint-id>

The exact input and output schema, price formula, estimated maximum cost (when signed in) and provider identity for one endpoint, before you run it. Works signed out too, on the public catalog.

catalog

looot catalog endpoints [--provider ID] [--category ID] [--platform ID] [--capability ID]
  [--limit 1..5000] [--cursor CURSOR] [--keyless true|false] [--mock true|false]
  [--facets true|false] [--max-price-micros N]

looot catalog search --query TEXT [same filters as endpoints]

looot catalog list | inspect <id> | compare <id1> <id2> ...

Published operation metadata. Provider-only prices are not quotes, and execution availability is a separate check from listing. catalog list, catalog inspect and catalog compare read the public catalog and work signed out.

run

looot run <endpoint-id> --input '{"...": "..."}' [--idempotency-key KEY] [--wait[=seconds]]

Starts, or replays, a run. An omitted --idempotency-key is generated on the CLI itself, printed to stderr, and safe to reuse on a retry (see Idempotency). --wait blocks and prints the finished run inline, not the queued or running one. It takes whole seconds, 0 to 60: 0 returns at once, the default is 20 when --wait is passed bare, and a value above 60 waits 60 and says so on stderr.

runs

looot runs get <run-id>
looot runs list [--status ...] [--capability ...] [--limit N] [--cursor CURSOR]
looot runs cancel <run-id>
looot runs attempts <run-id>
looot runs evidence <run-id>

runs evidence prints the same attempts JSON as runs attempts; in human output it also adds the input fingerprint, provider request and receipt ids, and quote and ledger entries.

balance

looot balance

Available and reserved balance for this workspace, and topUpLink.minimumUsd for the minimum top-up.

ledger

looot ledger list [--limit 1..50] [--cursor CURSOR]

Lists ledger entries for this workspace. Needs the usage.read scope.

mcp

looot mcp install --client claude-code|cursor|codex|generic [--auth-mode env|embedded]
  [--token-env NAME] [--show-token]

Writes an offline Streamable HTTP client config pointed at $LOOOT_API_URL/mcp. Prefer looot init, which does this for you across every detected client. HTTPS is required except on loopback. Embedded mode prints a placeholder where your token goes, unless you pass --show-token (which warns on stderr).

Not in 1.1.0 yet

The live gateway already accepts these; the next CLI release adds the flags. Use MCP or REST until then.

See Fallback and Jobs for what these do.