CLI Setup

Install the command-line tool for creating apps.

Prerequisites

For Python Apps: uv

The CLI uses uv for Python environment management:

1# macOS / Linux2curl -LsSf https://astral.sh/uv/install.sh | sh34# Windows5powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

For Node.js Apps: Node.js

Node.js v20 or later:

1# macOS / Linux (via fnm)2curl -fsSL https://fnm.vercel.app/install | bash3fnm install 2245# Or via nvm6curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash7nvm install 22

Hardware

Install CLI

1curl -fsSL https://cli.inference.sh | sh

This covers macOS, Linux, and Git Bash on Windows. In Windows PowerShell:

1irm https://cli.inference.sh/install.ps1 | iex

Both install to ~/.local/bin and add it to your PATH. Open a new terminal afterwards. On Windows, pass JSON input from a file (belt app run <app> --input input.json) because PowerShell strips the quotes from inline JSON.

Or via package managers:

1brew install inference-sh/tap/belt       # macOS / Linux2npx @inferencesh/belt                    # Node.js3scoop bucket add inference https://github.com/inference-sh/scoop-bucket && scoop install belt  # Windows

Command name

The same CLI is available as belt, infsh, and inferencesh (package installs may expose one or all of these names). Subcommands are identical:

1belt version2infsh version    # same CLI

Examples in this documentation use belt. Either prefix works.

Verify

1belt version

Update CLI

1belt update    # or: infsh update

Shell installer (curl … | sh): belt update downloads and replaces the binary in place.

Homebrew or Scoop: the CLI detects package-manager installs and refuses to self-update over a managed binary. Run the manager's command instead:

1brew upgrade belt    # Homebrew2scoop update belt    # Scoop

If you installed with brew install inference-sh/tap/belt or scoop install belt, belt update prints the matching command when an upgrade is available.

Auto-update runs in the background on most commands. It is skipped for belt version, belt update, and help flags. Set INFSH_NO_AUTOUPDATE=1 to disable automatic upgrades.

Dev builds (version dev, typical of go run or local builds) skip self-update so a release binary does not overwrite your working tree. belt update prints skipped: dev build. Pass --force to check the manifest and upgrade anyway:

1belt update --force

Login

1belt login2belt login --key-stdin < key.txt          # non-interactive: skip browser flow (CI, scripts)3printf %s "$KEY" | belt login --key-stdin

Opens a browser for device authorization in interactive terminals.

Headless device auth: in non-interactive shells (no TTY, CI set, BELT_NON_INTERACTIVE=1, or --no-input), belt login without --key prints an approval URL instead of opening a browser. After you approve, the browser page shows a 6-digit code. Run belt login --code <code> (-c) on the same machine to finish. The link and the code expire 5 minutes after belt login ran. The CLI keeps the PKCE verifiers of up to five recent unclaimed runs and tries them newest first, so a code from an earlier belt login on the same machine still works inside that window. If the claim fails, run belt login again for a fresh link.

For scripts and CI, pipe an API key with --key-stdin (or --key -) or set INFERENCE_API_KEY instead. --key <key> still works but warns: a key on the command line lands in shell history and the process list.

The CLI, the SDKs and curl examples all read INFERENCE_API_KEY (see Authentication). INFSH_API_KEY still works but is deprecated: belt prints a warning once per run, and when both are set and differ, INFERENCE_API_KEY wins.

Credentials are stored in ~/.inferencesh/config.json with 0600 permissions (owner read/write only). Other local belt data (skill cache, command history, hook logs, remote machine keys, and similar) defaults to ~/.belt/ and paths under ~/.inferencesh/. Set BELT_CONFIG_DIR to use one directory for all of it — config, cache, history, and remote identity — so separate agents or shells on the same machine never share login or cached skills. See Environment Variables.

A belt login session token slides on use like a browser session: regular CLI use extends server-side expiry (seven-day idle window) without changing the stored token, so you are not logged out a fixed week after login while you keep using belt. Short-lived sessions from device approval (custom expires_in under seven days) are not extended. See Device authorization — Sliding lifetime.

After a successful login, the CLI clears the skill cache and notice cooldowns under that layout (~/.belt/cache and ~/.belt/notices by default), so cached API responses start fresh for the new account.

Logout

1belt logout

Clears the stored credentials in ~/.inferencesh/config.json: API key, session token, anonymous session token, and any workspace override from belt auth switch. Also clears ~/.belt/cache and ~/.belt/notices.

Everything else under ~/.belt and ~/.inferencesh is kept, including command history (~/.belt/history), agent session ledgers (~/.belt/sessions), the hook log (~/.belt/hooks.log), and CLI logs.

INFERENCE_API_KEY in the environment is not cleared. Unset it separately.

Logout removes credentials from your machine only. To revoke a session on the server, use settings → personal → sessions or POST /oauth/revoke (see Device authorization: Revoke). API keys stay valid until you revoke them with belt keys revoke or delete them in settings → workspace → api keys.

When no credential is stored, the command prints not logged in and exits 0.

Reset

1belt reset

Clears all local belt state: the credentials in ~/.inferencesh/config.json, ~/.belt/cache, ~/.belt/notices, ~/.belt/sessions, ~/.belt/hooks.log, the pending headless login (~/.inferencesh/pending_auth.json), and the log directories ~/.inferencesh/logs and ~/.inferencesh/logs-staging.

Command history (~/.belt/history) is kept.

Reset does not revoke server-side sessions or delete API keys. For credential-only cleanup, use Logout.

Check your account

1belt me2belt me --json    # same payload as GET /me — for scripts and automation

Shows your username and workspace. When a workspace override is active, belt me prints a hint to use belt auth switch.

With --json, stdout is compact JSON for the GET /me response (user and team objects). Use --pjson for indented output. See Workspaces API: get current user. On failure, stdout is a JSON error object (same as other --json / --pjson commands); stderr still has the formatted message.

Logged in? belt auth status (alias whoami) prints the account and workspace the stored credential resolves to, and exits non-zero (auth-required) when there is no credential or the server rejects it. With --json: {"logged_in", "email", "team", "credential", "endpoint"}.

1belt auth status --json || printf %s "$KEY" | belt login --key-stdin

Balance: belt balance is a top-level alias for belt me balance (agents often try belt balance first). It prints your workspace's current balance and nudges you to top up when below $5. Use --json for {"balance": <microcents>, "balance_dollars": <float>}.

1belt balance2belt me balance --json

Requires billing:read scope (included in standard API keys). See Billing API.

Switch workspaces

If you belong to multiple workspaces, switch the active workspace for all CLI commands:

1belt auth switch              # interactive team picker2belt auth switch my-org       # switch directly by team username3belt auth sw my-org           # alias

The CLI stores the override in ~/.inferencesh/config.json and sends it as the X-Team-ID header on API requests. Switching back to your default workspace clears the override. Each successful switch also clears ~/.belt/cache and ~/.belt/notices, the same as login.

Temporary token for scripts

1belt auth token

Mints a short-lived API key from your login and prints it to stdout with no trailing newline — for subshells, curl, and shell scripts. The login credential itself stays in ~/.inferencesh/config.json.

1curl -H "Authorization: Bearer $(belt auth token)" https://api.inference.sh/me2export INFERENCE_API_KEY=$(belt auth token --ttl 8h)

The key is pinned to the active workspace (belt auth switch) and cannot act in any other workspace, even ones you belong to.

The key is a regular API key with a short expiry — see temporary keys. It cannot create other keys, so a leaked one cannot renew itself. While it is live it shows in your API keys list, where you can revoke it; once expired it is removed.

Works from a belt login session. Creating keys is held by your own sign-in, so an API key login cannot. When not logged in, errors go to stderr and stdout stays empty.

For a long-lived personal or workspace key, use belt keys or the web app.

Manage API keys

Create, list, and revoke API keys in the active workspace (belt auth switch). Requires belt login or INFERENCE_API_KEY, with the same capabilities as the REST API: every member manages their own personal keys; workspace owners and admins also manage workspace keys and every member's keys.

1belt keys create laptop2belt keys create ci --workspace --scope apps:execute --ttl 90d3belt keys list4belt keys revoke <id> -y

Personal keys (the default) act as you in the active workspace and stop working when you leave it. Workspace keys (--as workspace or --workspace) act as the workspace and survive their creator; only workspace owners and admins can create them. See API keys.

Use belt auth token for short-lived keys in scripts (24 hours at most, always personal). Use belt keys create for CI deploy keys, shared automation, or named keys you rotate yourself.

Doctor commands

belt auth doctor, belt app doctor, and belt plugin doctor share the same automation contract:

• Without --check, each command is a diagnostic report and exits 0 even when it finds problems — useful for humans reading the output.
• With --check, the command exits non-zero when the report is unhealthy — for CI gates and agents.
• With --json (or --pjson), stdout is a JSON report with a top-level ok boolean.

1belt auth doctor --check --json --no-input2belt app doctor --check --json3belt plugin doctor --check --json

Authentication (belt auth doctor)

1belt auth doctor2belt auth doctor --check --json --no-input

Config being present is not the same as credentials being accepted — a stored session expires, an API key is revoked, or the endpoint may be unreachable. belt auth doctor runs four checks:

With --check, any failed check sets a non-zero exit code. The exit code reflects the first failing check:

• Credential or auth failures → exit 4 (auth_required)
• Network or endpoint unreachable → exit 8 (retryable)
• API rate limit → exit 7 (rate_limited)

Use --json for machine-readable output:

1{2  "ok": false,3  "endpoint": "https://api.inference.sh",4  "checks": [5    {"name": "config", "status": "ok", "detail": "/home/user/.inferencesh/config.json"},6    {"name": "credential", "status": "fail", "detail": "none configured", "hint": "run 'belt login', or set INFERENCE_API_KEY"},7    {"name": "api", "status": "skipped", "detail": "no credential to test"}8  ]9}

Check statuses: ok, warn, fail, skipped. Failed checks include a hint with suggested next steps. The path check only warns, so it never fails --check. See Troubleshooting: Stale CLI on PATH.

App health (belt app doctor)

1belt app doctor2belt app doctor fix3belt app doctor --check --json

Run from your app directory before deploy. The doctor checks inf.yml, required files (inference.py / src/inference.js, dependency manifests), Python package layout (__init__.py, relative imports), Node ESM config, GPU dependencies, stale schemas, and other common issues. Errors block belt app deploy; warnings are shown but do not stop the build.

belt app doctor fix auto-fixes issues marked fixable (relative imports, missing __init__.py, GPU accelerate dependency, ESM type: module, and similar).

With --check, only errors gate the exit code — warnings are reported but do not fail the run. When errors are found, --check exits 10 (config): local project setup is missing or invalid (for example no inf.yml, a bad import, or an uninitialised project). Warnings alone still exit 0. With --json, stdout is:

1{2  "ok": false,3  "issues": [4    {5      "id": "missing-init",6      "message": "missing __init__.py — has sibling modules (utils.py) but no package init",7      "fixable": true,8      "severity": "error",9      "fix_description": "create __init__.py with `from .inference import App`"10    }11  ]12}

Issue fields: id, message, severity (error or warning), fixable, and optional fix_description / extra. → Deploying

Plugin health (belt plugin doctor)

1belt plugin doctor2belt plugin doctor --fix3belt plugin doctor --check --json

Checks belt CLI availability, authentication, agent runtime installs, plugin cache and hook configuration (Claude Code / Codex), hook shim format, and recent activity in ~/.belt/hooks.log. Use --fix to auto-repair stale caches, reinstall the belt plugin, and patch hook scripts that still contain embedded logic instead of the thin shim format.

With --check, any failed check exits non-zero. With --json, stdout is:

1{2  "ok": false,3  "checks": [4    {"name": "belt", "ok": true, "detail": "/usr/local/bin/belt"},5    {"name": "auth", "ok": false, "detail": "not logged in"},6    {"name": "plugin", "ok": false, "detail": "belt not found in installed plugins"}7  ]8}

Check names vary by detected agent runtime (for example plugin, hooks, shims, cursor, pi-ext). → Coding agents · Troubleshooting

What you can do

Development

Running Apps

For multi-function apps, belt app sample defaults to the resolved default function (run, explicit default_function, or the sole function). Use -f / --function for other entry points. belt app get lists all functions with run/sample hints.

When an app is missing required secrets or credentials, belt app run (and belt agent run) prints categorized setup hints instead of a generic API error — for example belt secrets set <KEY> (prompts for the value) or belt credentials connect <provider>. MCP requirements suggest belt mcp connect <slug>. When a requirement names no provider, the hint is connect at: https://app.inference.sh/vaults. The same requirement shape is returned by POST /run as HTTP 412 — see Check requirements.

JSON input — belt app run, belt mcp run, and belt flow run resolve input from three sources, in priority order: --input / -i flag → positional argument → piped stdin (when stdin is not a TTY). Each source accepts inline JSON ('{"prompt": "a cat"}'), @filename, or a path to an existing JSON file.

1belt app run namespace/my-app '{"prompt": "a cat"}'          # positional2echo '{"prompt": "a cat"}' | belt app run namespace/my-app   # stdin3belt mcp run linear:list_issues '{"project": "INF"}'         # positional4belt flow run abc123 --input '{"text":"hello"}' -f           # flag (unchanged)

Omit input entirely when the app, tool, or flow does not require it.

Filter output (--jq) — belt app run and belt mcp run accept --jq with a jq expression to filter JSON on stdout without piping to an external jq binary (the CLI embeds the same pure-Go engine GitHub CLI uses). String results are printed unquoted (like jq -r); other values are compact JSON, one per line.

1belt mcp run linear:list_issues --jq '.issues[] | {id, title}'2belt app run okaris/flux -i '{"prompt": "a cat"}' --jq '.output.url'3belt app run okaris/flux -i '{"prompt": "a cat"}' --no-wait --jq '.id'   # task id only

belt app run --jq evaluates against the task object (id, status, status_text, output, error, session_id, created_at, updated_at). App outputs live under .output — for example .output.url for a generated file URL. --jq suppresses progress lines on stdout (same as --json). Use --json or --pjson when you need the full task or tool payload instead.

belt app run exits 1 (error) when the final task status is failed or cancelled. With --json or --jq, stdout still contains the task JSON, so check $? or the status field. See Exit codes.

Output files — the task result prints to stdout (progress and status lines go to stderr), so belt app run … | jq and > out.json work. With --json, files lists every file the app produced (path and url, found from the app's output schema). --urls prints only those URLs, one per line. --download (bare form: current directory) or --download=DIR saves each file as <task>-<field>-<n>.<ext> and adds local_path to the JSON entries.

1belt app run okaris/flux -i '{"prompt": "a cat"}' --urls2belt app run okaris/flux -i '{"prompt": "a cat"}' --download=./out3belt app run okaris/flux -i '{"prompt": "a cat"}' --json --jq '.files[].url'

Batch — --batch prompts.jsonl (or - for stdin) runs one task per line and writes one JSONL result per input (index, task_id, status, output, error, submit_error, attempts). --concurrency N (default 4) bounds how many tasks are in flight; --retry N re-submits an input after a transient submit error (5xx, 429, network) or a provider-side task failure, with a 2s·attempt backoff.

1belt app run pruna/p-image --batch prompts.jsonl --concurrency 8 --retry 1 > results.jsonl

Cost estimation — belt app estimate reports the predicted cost of a run without dispatching a task. belt app run --estimate (-e) does the same when you already have a run command written. Both call POST /store/apps/{appId}/estimate with the same input handling as belt app run (inline JSON, @file, positional, or stdin). Apps with fixed per-call pricing can be estimated with no input; input-dependent pricing needs the intended input JSON.

1belt app estimate okaris/flux --input input.json2belt app estimate okaris/flux --input '{"prompt":"a cat"}'3belt app run okaris/flux --estimate --input '{"prompt":"a cat"}'4belt app estimate okaris/flux --input input.json --json --select microcents,confidence

Human-readable output shows estimated cost with a confidence level:

With --json, stdout is the full EstimateCostResponse (confidence, microcents, min, max, depends_on, pricing_description, estimate_error). → Estimate app cost · Usage-based pricing

Managing Apps

Programmatic listing:

1belt app list --json                         # your deployed apps (requires login)2belt app list --search "flux" --json3belt app list --limit 50 --cursor <next>     # cursor pagination (see hints in table output)4belt app store --json                        # public store with cursor pagination metadata5belt app store search "video" --category video --json6belt app store --save store-snapshot.json    # write JSON to file instead of stdout

belt app list --json prints the full cursor-list response from POST /apps/list (items as AppDTO[], plus next_cursor, has_next, …). belt app store --json prints the same cursor-list shape from POST /store/apps/list (items as PublicAppStoreDTO[]) — see List approved apps. In table output, both commands print next page: / prev page: hints with the --cursor value when more results exist. --save writes the store payload to a file (always pretty-printed) and prints a confirmation line to stdout.

belt app pull syncs app code and metadata from inference.sh:

1belt app pull              # sync current app (from inf.yml in cwd)2belt app pull --meta       # sync only the listing into inf.yml (no code)3belt app pull <app-id>     # download app by ID to namespace/name/4belt app pull --all        # sync every local app (finds inf.yml recursively)5belt app pull --all --meta # sync only the listing for every local app6belt app pull <app-id> --force   # overwrite existing directory without prompt

A pull merges into inf.yml; it does not rewrite the file (CLI 1.19.11 and later):

• The listing comes down from the platform: title, description, category and images. Use --meta after editing an app's images or description on its page.
• Everything else stays as you wrote it, including comments, key order and keys such as default_function, secrets and credentials. These reach the platform when you deploy.
• A value the platform does not have, such as an empty image or no title, leaves the local one in place.
• A full pull also takes the version's metadata and fills in keys the deployed inf.yml lacks.

An app pulled into a new directory gets namespace and name in its inf.yml, so deploy and run commands resolve the correct namespace/name ref.

If the name in inf.yml answers with a different app on the platform, because the app was renamed or redirected, the pull stops with an error and changes nothing.

When syncing an existing directory, the CLI removes old app files before extracting the new archive but preserves local environment and VCS paths: .git, .env, .infsh, .venv, venv, node_modules, and __pycache__.

belt app get shows schemas, pricing, and run/sample hints for an app ref (namespace/name, namespace/name@version-id, or app ID). With --json, stdout is {"app": <AppDTO>, "pricing": ...} from GET /apps/{ref}. When the ref (or a platform alias on it) pins a function, app.resolved_function names that entry point — see Get App.

1belt app get okaris/flux2belt app get okaris/flux@abc123 --versions   # version history3belt app get okaris/flux --json              # includes status fields for scripts

When lifecycle status is not active, human-readable output shows a banner after the description:

belt app run against a maintenance or retired app returns API errors (503 app_maintenance, 410 app_retired) — see Tasks API. Use belt app get before scripting runs to check status and the owner's message (for example, a replacement app ref).

belt suggest calls the same discovery API as GET /suggest. Results include a suggested CLI command or URL for each hit:

1belt suggest "flux image"2belt suggest "web search" --json     # JSON for agent hooks3belt suggest "deploy" --agent        # directive framing for agent hooks

With no arguments, belt suggest reads stdin (hook JSON or plain text). CLI args take precedence over stdin.

Human-readable output groups results by category (app, skill, knowledge, and so on). Each section header shows the category and a command template (for example belt skill use <name>). Result lines include an optional inline [tag], the name, and description. After a cross-collection search, stderr may suggest scoped follow-ups such as belt app suggest "...".

Hook mode (--json): Returns hookSpecificOutput.additionalContext with one line per match: - [type] name — description, then run: <command> on the next line. Results are ranked by score and deduped server-side. Hook stdin is JSON with a prompt field (or plain text). When transcript_path is present, belt extracts assistant text from the current turn (since the last user message, up to 1000 characters) and sends it as the context field to POST /suggest for semantic ranking — keyword matching still uses prompt only. Belt also sends scope signals from the current directory (git: remote, lang:, module:, and similar tags) on every suggest call so knowledge captured in the same repo or language ranks higher. API failures are silent in --json mode so hooks do not pollute agent stderr.

Use --agent to frame hook output as a directive to the agent. Descriptions in suggest results are always one line of at most 200 characters; load the resource to read the rest. Hook integrations installed via belt plugin install <agent> call belt suggest --json automatically.

belt suggest also sends scope tags from the current working directory (git remote, module name, language, path) so project-relevant knowledge ranks higher in results. Entries uploaded with belt know upload carry the same tags unless you used --global.

Use belt app search when you only need apps. Use belt suggest for cross-collection discovery (skills, knowledge, docs, and apps).

→ Search concept · Search API

Secrets

Connectors (MCP)

belt mcp run and belt mcp tools use slug:tool format — the first colon splits the server slug from the tool name (for example linear:list_issues). Pass only the slug to belt mcp run to list available tools instead of calling one. If you mistype an MCP subcommand, the CLI prints this format hint. After belt mcp list, stderr may show tips for belt mcp search, get, and connect.

belt mcp run <slug>:<tool> --help fetches that tool's schema (description, required fields, JSON Schema, and a sample belt mcp run … --input '…' line) before the usual usage text — the same detail as belt mcp tools <slug>:<tool>. Tool input is -i / --input, a positional JSON argument, or stdin; mistyped flags such as --args print the parse error on stderr plus a reminder instead of exiting silently. When the server returns is_error: true, stderr repeats the server's message when present and suggests belt mcp tools <slug>:<tool> for the schema; stdout still holds the full JSON payload. When the tool result is only one page of a larger list (next_cursor, has_more, pageInfo, and similar), stderr also hints how to pass the cursor in --input for the next page — see Using tools — Call a tool.

With --json, belt mcp tools prints the tool surface from the connected MCP server: an array of name, description, and inputSchema objects when you pass only the slug, or a single tool object when you pass slug:tool. Tool names, descriptions, and schemas are authored by the MCP server (third-party content), so combine --wrap-untrusted when piping this output to an LLM — see Global automation flags.

1belt mcp tools linear --json2belt mcp tools linear:list_issues --json3belt mcp tools linear --json --select name,description   # projection for agents

Some MCP tools need extra input mid-call (Multi Round-Trip Request / MRTR). In an interactive terminal, belt mcp run prompts for missing fields (form mode) or opens a browser for OAuth-style steps (URL mode), then retries automatically. In non-interactive mode (CI, no TTY, or BELT_NON_INTERACTIVE=1), the CLI prints the input_required JSON envelope to stdout and exits with code 2 — scripts must parse input_requests and call the API again with inputResponses. See Using tools — Interactive elicitation.

→ Connectors overview · Browsing connectors · Using tools

Credentials (CLI)

List, connect, and inspect OAuth, service account, and MCP credentials for your workspace:

1belt credentials list2belt credentials list --limit 50 --cursor <next>   # when stderr hints show more pages3belt credentials get google4belt credentials get mcp --json   # includes credential id for agent tools5belt credentials connect google6belt credentials connect slack7belt credentials disconnect google

belt creds is an alias for the same command group.

belt credentials connect looks up the provider in GET /credentials/configs. OAuth providers open your browser and poll for up to two minutes. API key providers prompt for each declared secret field (sensitive fields are masked), save each as the provider's credential (the same as belt secrets set <KEY> --provider <provider>), and report connected when the server marks the credential connected. Service accounts connect directly when the provider supports it. If the provider is already connected, the CLI prints the account and suggests disconnecting first. Unknown providers list available options; for MCP servers, use belt mcp connect <slug> instead.

Connection scope: Pass --as user|team|org|platform (or --team as shorthand for --as team) to set who owns the credential. The flag sets connection_scope on the connect request. Omit both flags to use the provider default. Invalid --as values are rejected before any API call. To change who owns an existing connection without reconnecting, use PUT /credentials/{provider}/scope — see Change connection scope.

1belt credentials connect google --as team      # team admin: shared team OAuth2belt mcp connect linear --as user              # personal MCP authorization (default for MCP)

Google OAuth and the managed service account are separate providers (google vs google-sa). Connect the service account from vaults → credentials (google-sa slug) or with belt credentials connect google-sa.

Non-interactive OAuth (CI, scripts): When stderr is not a TTY, CI is set, or BELT_NON_INTERACTIVE=1, belt credentials connect prints the authorization URL but does not open a browser or poll. Open the URL manually, then verify with belt credentials get <provider>. For API key providers in the same conditions, the CLI prints belt secrets set <KEY> --value-stdin --provider <provider> < value-file lines instead of prompting.

Provider keys match the REST API: google, google-sa, gcp, slack, mcp, and so on. MCP servers all sit under mcp; the server URL is the credential's account identifier, and GET /credentials/mcp?identifier={server_url} names one. Use belt credentials get --json when you need the credential id for agent connector tools.

→ Credentials API · Connectors overview

Vaults (CLI)

Inspect workspace vaults, the containers that group credentials and secrets. In the web app they are under vaults.

vault is an alias for vaults (for example belt vault show). Both commands are read-only.

1belt vaults list2belt vaults show                    # default vault3belt vaults show vault_abc123       # specific vault by ID4belt vaults show --json

belt vaults show with no argument resolves the workspace's default vault (GET /vaults/default). It prints two tables: credentials (provider, type, scope, status, display name) and secrets (key, value, description). Secret values are masked.

With --json:

• belt vaults list prints a VaultDTO[] array (id, name, description, is_default, credential_count, secret_count, ...)
• belt vaults show prints {"vault_id", "name", "credentials": [...], "secrets": [...]}

To connect credentials or set secrets, use belt credentials connect, belt secrets set, or the Vault UI.

→ Vaults API · Credentials overview · Environment secrets

Flows (CLI)

Create, edit, run, and publish flows from the terminal — same APIs as Flows and Flow Runs.

Flow refs — Commands that target a saved flow accept namespace/name or a flow ID (full flow_… ID or short ID). Resolution matches belt agent get and belt agent run: namespaced refs call GET /flows/{namespace}/{name}; IDs call GET /flows/{id}.

Graph editing — belt flow edit applies draft mutations via POST /flows/{id}/actions. The first argument is the same <ref> as belt flow get:

1belt flow get myteam/voice-pipeline         # by namespace/name2belt flow get abc123                        # by short ID3belt flow create --name voice-pipeline4belt flow edit node add myteam/voice-pipeline tts --app elevenlabs/tts5belt flow edit node set-input myteam/voice-pipeline tts text "hello world"6belt flow edit node set-input myteam/voice-pipeline voice-changer audio --from tts:audio7belt flow edit output set myteam/voice-pipeline audio --from voice-changer:audio8belt flow describe myteam/voice-pipeline9belt flow run myteam/voice-pipeline -f10belt flow publish myteam/voice-pipeline

Use input as the source node in --from to wire a node input to a flow-level input (for example --from input:text). belt flow run -f streams NDJSON progress events with polling fallback when SSE is unavailable.

→ Flows guide · Creating a flow · Flows API · Flow Runs API

Agent integration (CLI)

Wire belt into a local coding agent runtime (discovery hooks and core skills):

belt review is called by Stop and PreCompact hooks installed via belt plugin install <agent>. Claude Code plugin hooks call belt plugin review instead. It reads hook JSON from stdin, evaluates the session transcript, and saves reusable knowledge to your workspace. Each candidate is deduped against similar entries already in your registry (search, then create / update / skip) — see Knowledge API — extraction deduplication.

1belt review --agent cursor --trigger stop        # called by Cursor Stop hook2belt plugin review --trigger stop                # called by Claude Code Stop hook3belt review --agent claude-code --trigger stop   # same pipeline as belt plugin review4belt review --agent codex --dry-run                # preview without saving5belt review --agent cursor --force                 # skip 10-turn gating

Claude Code uses fork-based extraction and can auto-publish skills. Other agents use transcript-based extraction through the inference.sh API. Requires belt login.

→ Coding agents — skills directories, hook behavior, and Claude Code details

Agents (CLI)

belt agent create calls POST /agents with a first version. Use it for quick agents from the terminal; use belt agent deploy when you need skills, context fields, output schema, or other YAML-only options.

Redeploying the same agent name creates a new version instead of failing with a name conflict. This is the same upsert behavior as belt app deploy. The namespace is assigned from your active workspace server-side, so the namespace field in YAML is optional. You only need a stable name in the file to update an existing agent.

1belt agent create my-helper "A helpful assistant"2belt agent create todo-bot --model openrouter/claude-sonnet-46 --prompt "You manage Todoist tasks"3belt agent create todo-bot --model openrouter/claude-sonnet-46 \4  --mcp 46e8a4bq...:find-projects \5  --mcp 46e8a4bq...:add-tasks6belt agent create my-bot --json    # raw AgentDTO on stdout

On success, the CLI prints namespace/name@version-id for use with belt agent run.

belt agent pull exports an agent version as YAML for local editing and redeploy. Ref format matches belt agent get and belt agent run (namespace/name, namespace/name@version-id, or agent ID). Print to stdout or save with --save / -o:

1belt agent pull myteam/support-bot2belt agent pull myteam/support-bot@abc123 --save agent.yml

YAML from pull is intended to round-trip through belt agent deploy without losing configuration: call and http tool auth, headers, and JSON schemas; client tool input_schema / output_schema; skill skill_id and version_id pins; preload (system-prompt injection vs on-demand skill_get); inline skill content for text-defined skills; the permissions block (today allow_all_tools, copied into each new chat created in the agent's own workspace so unattended runs do not stall on tool approval); and lifecycle hooks, including the builtin learning hooks. Redeploying YAML that omits hooks clears hooks that were configured in the editor or on a prior version. See Skills on agents, Adding skills, and Approval settings.

Lifecycle hooks go under hooks. To turn on the learning hooks (the suggest and learn switches in the agent editor):

1hooks:2  - { event: agent.turn_start, type: builtin, handler: "belt:suggest" }3  - { event: agent.complete, type: builtin, handler: "belt:extract" }4  - { event: agent.pre_compact, type: builtin, handler: "belt:extract" }

Before belt v1.19.4, belt agent deploy ignored hooks and deployed a version without them. Update the CLI before redeploying an agent that has hooks. See Lifecycle hooks.

belt agent get accepts the same refs as belt agent run — namespace/name, namespace/name@version-id, or agent ID. With --json, stdout is the full AgentDTO from GET /agents/{ref}.

1belt agent get myteam/support-bot2belt agent get myteam/support-bot@latest3belt agent get agent_abc123

Human-readable output uses lowercase labels and lists attached skills with their resolved ref and version pin:

1  agent:  myteam/support-bot2  version: abc1233  description: Handles customer support4  system prompt: You are a helpful support agent...5  core app: openrouter/claude-sonnet-4667  tools:8    - search (call): Search the web910  skills:11    - myteam/pricing-rules@ver_xyz: Pricing guidelines1213  context:14    - tenant_id (required): Tenant identifier

Each skill line shows skill_id@version_id when the agent pins a specific skill version; otherwise it falls back to the skill name from the agent definition. System prompts longer than 200 characters are truncated.

With --no-wait, the CLI returns as soon as the run is accepted. Without --json, it prints Chat started: <chat-id> with muted belt chat get / belt chat pending hints. With --json --no-wait, stdout is only {"chat_id": "<id>"} — use this in scripts that poll with belt chat get or belt chat watch.

Without --no-wait, belt agent run streams chat events until the agent finishes, needs approval, or hits --timeout (default 4m). On timeout, the CLI prints the chat ID so you can follow up with belt chat get or belt chat pending. With --json (and no --no-wait), stdout is the full POST /agents/run response after streaming completes. Tool calls print as muted progress lines while they run:

1→ calling search...2→ search completed

Failed tools print → {name} failed. The final assistant message is printed when the run completes. After a successful run, the CLI prints a muted continuation hint with the chat ID — use belt chat send <chat-id> "<message>" for follow-ups without starting a new run.

Chat (CLI)

Manage agent conversations and human-in-the-loop approvals from the terminal:

When belt agent run stops at awaiting_input, the CLI prints belt chat approve / reject commands for each pending invocation. For the unified interrupt model (widgets, auth gates, hook gates, and tool approvals), use belt interrupt list on the run ID from belt chat get --json — see Interrupt (CLI).

belt chat get shows the last 3 messages by default. Use --last N for more, --all for the full transcript, or --full to disable truncation of message text and tool argument JSON (default truncates at 200 and 100 characters respectively). Pending tool invocations always show full args and an approve: hint.

belt chat send posts your message via POST /chats/{id}/messages and then streams chat events until the agent finishes, needs approval, or the stream times out (4 minutes) — the same SSE path as belt agent run without --no-wait. Tool calls print as muted progress lines (→ calling {name}... / → {name} completed or failed). If the agent stops at awaiting_input, the CLI prints belt chat approve / reject commands. With --json, stdout is the created user message from POST /chats/{id}/messages immediately after the message is accepted, without waiting for the agent to finish — poll with belt chat get --json or run belt chat watch if you need the final transcript in automation.

Use belt chat watch when you did not just send a message — for example after belt chat approve without --watch, or to re-attach to a chat that is already busy.

Interrupt (CLI)

List and resolve interrupt gates on agent runs. Interrupts are the unified gate model when a run pauses for tool approval, widget input, missing credentials, lifecycle hook gates, or other external input (active_run.state is input_required or auth_required). For tool-approval interrupts (reason: tool_approval), belt interrupt resolve … allow is equivalent to belt chat approve; deny is equivalent to belt chat reject.

1# List pending interrupts for a run (run ID from belt chat get --json active_run.id)2belt interrupt list run_abc12334# Allow or deny a specific interrupt5belt interrupt resolve int_abc123 allow6belt interrupt resolve int_abc123 deny78# JSON output for scripting9belt interrupt list run_abc123 --json10belt interrupt resolve int_abc123 allow --json

With --json, list prints an array of InterruptDTO objects; resolve prints the updated interrupt. The table output shows interrupt ID, reason, source, and resource (resource ID).

→ Agents REST API — Interrupt gates · Approval settings · Human-in-the-loop

Skills (CLI)

Refs use namespace/name or namespace/name@version-id (same as the REST API). belt skill use without a version fetches the latest.

belt skill list --json prints a page-based list envelope: items as SkillDTO[], plus total, page, pages, has_next, and has_previous. Pagination uses --page (20 per page). --search / -q filters by name or description. --save / -o writes the same shape to a file (pretty-printed). Entry fields match List Knowledge items. Use --results-only --select to project fields from items — keys are stable snake_case in release builds.

belt skill use does not inline supplementary files. When a skill has extra files, stderr prints tips for belt skill add and belt skill files.

A skill version holds only the files in that upload. When updating an existing skill, belt skill upload refuses to publish if the upload omits supplementary files the current version has (for example after uploading a lone SKILL.md over a skill with references/). The error lists the paths that would be dropped. Upload the full skill directory, or pass --prune to publish without the missing files after you remove or rename them locally. New skills are not checked.

belt know upload applies the same guard to every upload of type skill (directory, file, or stdin), with the same --prune flag.

belt skill versions requires belt login — it resolves the skill by name, then calls GET /knowledge/{id}/versions. The table marks the current version at the bottom.

belt skill supersede requires belt login. Both arguments are namespace/name refs or skill IDs. The old skill is hidden from belt suggest and other discovery results; the replacement skill is unchanged. Use this when you publish a replacement under a new name instead of versioning in place.

belt skill delete requires belt login. Pass a skill ID or namespace/name ref. The CLI resolves refs to an ID and soft-deletes the entry (same backend path as belt know delete). belt know delete accepts the same ref forms for any knowledge type. The skill is removed from search indexing and no longer appears in suggest results. Destructive: prompts for confirmation unless you pass --yes / -y. To keep a replacement discoverable instead of removing the old skill, use belt skill supersede.

1belt skill versions myteam/code-review2belt skill use myteam/code-review@abc123   # specific version3belt skill supersede myteam/old-review myteam/code-review4belt skill delete myteam/deprecated-skill --yes

→ Skill registry · Delete Skill API · Supersede Skill API · Search concept · Search API · Knowledge API — versions

Knowledge (CLI)

belt know is an alias for belt knowledge. Refs use namespace/name or namespace/name@version-id (same as the REST API).

belt know list --json uses the same page-based envelope as belt skill list --json (items, total, page, pages, has_next, has_previous). Filter with --type and --search / -q; paginate with --page. --save / -o writes the same JSON to a file (pretty-printed).

1belt know list --type observation2belt know get acme/onboarding              # latest version (no login for public entries)3belt know get acme/onboarding@abc123       # specific version4belt know upload ./my-skill/               # directory with SKILL.md → skill5belt know upload ./notes.md --type reference6belt know upload ./notes.md --global       # skip project scope tags

By default, belt know upload attaches project scope tags from the working directory (git remote, module name, language, path) so /suggest can rank the entry higher in matching projects. Pass --global to omit scope for workspace-wide references that should surface everywhere.

When belt know get finds supplementary files (references, scripts, examples), the CLI prints tips for belt skill add and belt skill files so you can install or inspect them locally.

belt know upload auto-collects scope signals from the current directory (git remote, module name, language) and stores them on the new version — see Knowledge — Project scope.

→ Knowledge API · Creating skills

Files (CLI)

belt file (alias belt files) lists, uploads, downloads, and deletes files in your workspace. Use it to save outputs from belt app run or belt mcp run without shelling out to curl.

1belt file list --type image --limit 202belt file list --search photo3belt file list -q avatar --type image4belt file download https://files.inference.sh/abc/image.png5belt file download 01abc123def456 -o ./output.png6belt file upload ./photo.jpg --name avatar.jpg7belt file upload *.png8belt file info 01abc123def456 --json9belt file delete 01abc123def456 --force

--type filters by content category (image, video, audio, text) — the CLI matches MIME types like image/%. --search / -q filters by filename substring (case-insensitive). Combine both to narrow results (for example -q avatar --type image). In table output, the type column shows short labels (image, video, audio, or subtypes like json, pdf, docx, csv, text) instead of raw MIME strings. Downloads accept a file URL (for example from task output) or a file ID from belt file list. If the destination filename already exists, download auto-renames with (1), (2) suffixes. Uploads and downloads show live progress (speed, bytes transferred, ETA); batch uploads print a [1/N] counter per file.

belt app run auto-uploads local file paths and data: URIs in --input JSON for schema fields with format: file — use belt file upload when you need a URI outside a task run. See SDK files — automatic upload.

→ Files API · SDK Files

Forms (CLI)

List, inspect, fill, and review submissions for schema-driven forms in your workspace (and public forms from other teams). Requires belt login.

1belt form list2belt form get infsh/use_case3belt form fill acme/feedback rating=5 role=dev langs=go,ts4belt form fill acme/feedback --data '{"rating":5}' --no-input5belt form fill acme/feedback --data-file answers.json --json6belt form submissions acme/feedback --limit 50

Refs use namespace/name (your workspace username is the namespace). belt form fill only submits when the form status is open.

Inspect. belt form get prints one block per question (never truncated): key, widget type, required/optional, full prompt text, description, choice labels, validation limits (length, numeric bounds, and similar), examples, and only if visibility rules. Use this before scripting belt form fill so agents see the same constraints the web app enforces.

Answers. Pass key=value pairs, --data (inline JSON or @file), or --data-file. Later sources override earlier ones; repeat a key to collect multiple values for multiple-choice questions. Values are coerced by question type (numbers for ratings, yes/no for yes-no, option labels or list indices for choices). In a terminal, belt prompts for any shown question still missing an answer; optional questions accept Enter to skip. Conditional questions appear and disappear as earlier answers change visibility (same rules as the web app).

Automation. With --no-input or without a TTY, every required visible question must be supplied up front or the command fails. Local checks (missing required answers, bad coercion) and API 422 field errors are reported together in question order. On stderr, each problem is one key: message line; when belt knows the accepted shape, the line adds — expects … (question kind, choice labels, and limits such as length or numeric bounds). A muted footer points at belt form get <ref> for every question with full prompts and limits. With --json, stdout is a single object { "error", "form"?, "missing"?, "fields"? }; each entry in missing or fields includes key, optional title, message, and expects when applicable, so agents can fix every problem without reading the whole form first. Answers to hidden questions are dropped; non-empty answers to questions that are not shown produce a muted warning.

Claims. belt form fill records answers only — it does not print credit amounts or grant rewards. When a bounty program uses the form as proof (proof_type: form), claim credits with belt bounty claim <program> (see below). That command reuses an existing submission or fills the form first in one step.

→ Forms API · Bounties (CLI)

Bounties (CLI)

List active credit programs from GET /bounties and claim them with a proof (form submission or deployed app). Requires belt login. Responses are cached locally for 6 hours (~/.belt/cache/bounty-programs.json).

1belt bounty list2belt bounty claim agent-survey3belt bounty claim agent-survey role=dev langs=go,ts --no-input4belt bounty claim agent-survey --data-file answers.json --json5belt bounty claim app-builder acme/my-app

belt bounty list --json returns {name, description, amount_microcents, reward, proof_type, proof_form?, command?, claimed?} per program. Form programs show claimed: true after a successful claim on this machine.

Form programs. Use belt form get <proof_form> to inspect every question before scripting. With --no-input or without a TTY, missing required answers exit 2 and print the same structured errors as belt form fill (expects hints and a belt form get footer). When a saved payment method is required, exit 9 includes billing_url and the exact belt bounty claim … command to rerun; your answers are kept.

App programs. The app must be deployed on inference.sh. belt bounty claim app-builder <namespace/app> is the same as belt app promo submit <namespace/app> (alias). Typical rules: useful app, not a duplicate of an existing listing, public after claim, daily limit per program — see belt app promo help.

belt bounty claim --json prints one object: status is claimed, payment_method_required, already_claimed, or failed; missing form answers use the fill object {error, form, missing, fields} on stdout.

→ Bounties API

App bounties (CLI)

The app-builder program pays workspace credits for useful apps you deploy and make public. Reward amounts and claim limits come from GET /bounties and can change without a CLI release; belt bounty list shows the current offer (belt app promo points there instead of naming an amount).

App-builder rules (also shown by belt app promo):

1. The app must be deployed (belt app deploy).
2. The app must be useful and not duplicate something already on the platform.
3. Python or JavaScript apps are fine — simple utilities are great candidates.
4. Submitting agrees to make the app public so other agents can reuse it.
5. One claim per day for this program (max_per_day on the API) — check belt bounty list for limits on other programs.

1belt bounty list2belt skill use inference-sh/building-inferencesh-apps   # optional starter skill3belt app deploy4belt bounty claim app-builder myteam/my-utility5# same as: belt app promo submit myteam/my-utility

Claims call POST /me/bounty with bounty_id set to the program name and proof_id set to your app ID; the CLI accepts namespace/name and resolves the app. When the program sets requires_payment_method and the team has no saved payment method, the API returns 402 payment_method_required and records nothing; add a card under team billing payments and run the claim again.

Feedback (CLI)

Submit customer-discovery answers and open feedback. Responses are stored on your account via POST /me/survey (requires belt login).

Structured question IDs: use_case, discovery, need, testimonial (legacy feedback is still accepted by the API). Which questions are active, and the exact wording and options, come from active bounty programs named survey-<id> and the matching platform form infsh/<id> (first question in the schema). When the API cannot be reached and nothing is cached, the CLI falls back to built-in wording for those four IDs.

1belt feedback                                    # see what's pending2belt feedback discovery "found it on github"3belt feedback use_case "building AI agents for customer support"4belt feedback need "better template discovery"5belt feedback testimonial "fastest way to ship agents with real integrations"6belt feedback "love the speed, wish there were more templates"

Survey answers are stored with POST /me/survey. belt feedback does not claim credits; a survey-<id> bounty is claimed separately with POST /me/bounty (see Bounties). The API rejects placeholder template text and stores nothing.

Bounty forms. Programs with proof_type: form name the form in proof_form (for example infsh/marketplace_waitlist). With belt login, belt feedback lists those programs (excluding single-question survey-<id> entries). Each line shows the title, reward, and belt bounty claim <program>. Lines show ✓ when the program is already claimed on this machine. Use belt bounty list for the same programs in table or JSON form.

Before most commands, the CLI may show one due bounty or survey notice at the top of stderr (the notice block). Programs come from GET /bounties (cached 6 hours); the CLI walks them in notice_priority order and respects each program's notice_cooldown_hours. Survey programs (survey-<id>) use the same wording as belt feedback (from infsh/<id> when available). Form programs use notice_text or earn $X — <description>, ending with belt bounty claim <program>; they keep appearing until claimed on this machine. Single-question surveys use a 1-hour cooldown per question; when every active structured question is answered, an occasional freeform prompt (72-hour cooldown) suggests belt feedback "...". Notices are skipped for belt version, belt update, belt feedback, belt login, belt logout, belt bounty, and belt app promo so scripts and agents parsing those commands get clean output. A logged-out session does not spend survey notice cadence.

Survey prompts are not injected into belt suggest --json hook output — only the stderr notice path above. Submissions include optional metadata: agent (detected runtime, e.g. cursor) and context (your five most recent belt commands, comma-separated).

The CLI records the last 10 commands you run in ~/.belt/history (via the post-command tips hook; skipped for belt feedback itself and when tips are suppressed with INFSH_NO_TIPS=1, --json, --pjson, or --jq, or when stderr is not a terminal). When you submit feedback, the last five entries are sent as context.

Survey prompts and other stderr tips are silent when stderr is not a terminal or CI / BELT_NON_INTERACTIVE is set. Inside a coding agent, only UserKnowledge survey questions (worded for the operator to answer) and bounty forms (intended for the agent to complete with belt bounty claim <program> … --no-input) appear in the notice block; cash bounties and self-answerable surveys are hidden so the agent does not claim rewards on the operator's behalf. INFSH_NO_TIPS=1 disables them everywhere.

belt skill use keeps a copy of each resolved skill under ~/.belt/cache/skills/ and serves the newest cached copy, with a stderr note, when the API is unreachable.

→ Survey API · Forms API · Bounties (CLI) · Coding agents

Remotes (CLI)

Connect a machine to inference as a remote and optionally run commands on it. See Remotes for the security model and workflow.

1belt login2belt remote start --name work-laptop --exec    # opt in to command execution3belt remote start --agents                     # opt in to harness agent sessions4belt remote exec remote_abc123 -- ls -la5belt remote exec remote_abc123 -- bash -c "cd /tmp && make test"

belt remote start requires login and the remotes:write scope. It creates a machine identity key in ~/.inferencesh/ (or BELT_CONFIG_DIR when set), probes for installed agent harnesses (from the agentprotocol registry), registers with POST /remotes, and keeps an authenticated WebSocket open to inference. Registration is scoped to your active team (belt auth switch); restart the daemon after switching teams. Press Ctrl-C to disconnect a foreground daemon.

Starting again with different --exec or --agents than the running daemon offers to restart it (agent sessions on that machine end). Decline or run without an interactive terminal and belt tells you to belt remote stop first. Flags belong on belt remote start, not bare belt remote. belt remote list shows account remotes; after seven days without a heartbeat it suggests belt remote rm for stale rows.

Exec opt-in. Command execution is off by default. Start the daemon with --exec so it accepts remote_exec_start frames. Without --exec, belt remote exec gets 403 exec_disabled from the API.

Agent sessions opt-in. Harness sessions are off by default. Start the daemon with --agents so it accepts remote_session_* frames and registers agents_enabled: true. Without --agents, the daemon refuses session opens with agent sessions are disabled on this remote (start it with --agents). This is separate from --exec. See Agent harness sessions.

belt remote exec streams stdout/stderr as output arrives and exits with the remote command's exit code. It is marked destructive (confirmation prompt, --yes in non-interactive mode). Automation should call POST /remotes/{id}/execs and poll GET /execs/{id}/output. See Remotes API.

→ Remotes guide · Remotes API

Tasks (CLI)

Cancel a running task before delete or delete-files. belt task files lists only files stored on inference.sh; external https:// URLs in input are not listed.

1belt task files task_abc2belt task files task_abc --role output --json3belt task delete-files task_abc --yes          # destructive — confirm in scripts4belt task delete task_abc --files --yes        # remove task and its platform files

For HTTP equivalents, see Tasks API (list, logs, timings, telemetry, status, delete, and file endpoints). Resource telemetry is available via GET /tasks/:id/telemetry or client.tasks.getTelemetry(id) in the JavaScript SDK.

Automation contract

Belt exposes a machine-readable contract for agents, CI, and scripts. stdout is data; prompts, progress, and diagnostics go to stderr.

belt schema

Print the complete command tree, flags, and automation guarantees as JSON. The output describes the binary that is actually running, so it stays correct as commands change. Schema output is always indented JSON — --json is not required.

1belt schema                              # full contract2belt schema app run                      # one subtree3belt schema --include-hidden             # hidden commands and flags4belt schema --include-inherited          # repeat global flags on every command node5belt schema | jq '.automation.exit_codes'   # exit-code table only

Top-level fields:

Each command node includes an effect field that tells agents what running it does:

Pass a command path to scope to one subtree. An invalid path exits 2 (usage).

Destructive commands

Commands that remove or halt remote resources prompt for confirmation before acting. Declining the prompt exits 130 (cancelled) without sending a request — the resource is unchanged. In non-interactive mode (--no-input, CI, or BELT_NON_INTERACTIVE=1), destructive commands refuse to run without --yes / -y and exit 2 (usage).

Pass --yes / -y to skip the confirmation prompt. belt file delete also accepts --force / -f (predates --yes; same effect).

1belt agent delete myteam/old-bot --yes2belt file delete 01abc123 --force           # equivalent to --yes3belt task cancel task_abc --yes             # confirm unattended cancel

--yes is separate from domain flags like belt task cancel --force, which means hard kill instead of graceful drain — it does not skip the confirmation prompt.

Exit codes

Belt exits with stable numeric codes so automation can branch without parsing stderr. Existing codes keep their meaning; unrecognized failures exit 1 (error).

Read the live table from belt schema | jq '.automation.exit_codes'. With --json or --pjson active, failures also write a JSON error object to stdout (see below).

Compact help for agents (BELT_HELP=agent)

When BELT_HELP=agent is set, belt help (or running belt with no subcommand) prints a compact automation summary instead of the full grouped command tree — output formats, discovery commands, common reads, and the exit-code table. Individual belt <command> --help output is unchanged.

1BELT_HELP=agent belt help

Global automation flags

With --wrap-untrusted, text belt did not author — MCP tool listings and results, skill instructions, knowledge entries — is framed with <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers and a security notice so an LLM can distinguish data from operator instructions. JSON output uses in-place neutralization plus an externalContent provenance object so the payload stays parseable. Applies to commands that fetch external content (for example belt mcp tools, belt mcp run, belt skill use, belt know get).

JSON output (--json / --pjson)

Many commands accept --json (-j) for machine-readable output on stdout. As of CLI v1.15.13, --json writes compact single-line JSON so it pipes cleanly to jq and other tools. Use --pjson when you want indented JSON for human debugging in the terminal.

For belt app run and belt mcp run, --jq '<expr>' filters output inline (no external jq required) — see Filter output (--jq) above.

Both flags suppress contextual stderr tips (post-command tips only — hook tip: lines inside belt suggest --json output are unchanged). On belt mcp run, --jq suppresses those tips as well so piped or merged streams stay machine-readable. Tips are also skipped when stderr is not a terminal (for example when an agent captures stdout and stderr together). Commands that support --save (for example belt app store --save) always write pretty-printed JSON to the file, regardless of --json or --pjson.

Output projection (--results-only, --select)

Global flags that shrink JSON output for agents and scripts. Both require --json or --pjson — using them without a JSON mode is a usage error (exit 2).

Both are applied centrally on every JSON stdout path (including belt mcp run, which holds raw upstream payloads), so list commands support them without per-command opt-in.

1belt know list --json --results-only --select id,name2belt app list --json --results-only --select id,namespace,name3belt skill store --json --results-only --select namespace,name4belt mcp run linear:list_issues --json --select id,title5belt mcp tools linear --json --select name,description6belt task list --json --select id,status