CLI Setup

Install the command-line tool for creating apps.

Prerequisites

For Python Apps: uv

The CLI uses uv for Python environment management:

1curl -LsSf https://astral.sh/uv/install.sh | sh23# Windows4powershell -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 cli.inference.sh | sh

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

Connector and MCP examples in this documentation often use belt. App development examples use infsh. Either prefix works.

Verify

1infsh version

Update CLI

1belt update    # or: infsh update

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.

Login

1infsh login2belt login --key inf_…   # non-interactive: skip browser flow (CI, scripts)

Opens a browser for device authorization in interactive terminals. In non-interactive shells (no TTY, CI set, or BELT_NON_INTERACTIVE=1), pass --key or set INFSH_API_KEY instead.

Check your account

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

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

With --json, stdout is the indented GET /me response (user and team objects). See Teams API — Get current user. On failure, diagnostics go to stderr only — stdout stays empty (no {"error":...} object).

Switch teams

If you belong to multiple teams, switch the active team context 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 team clears the override.

Print API key for scripts

1belt auth token

Prints the stored API key to stdout with no trailing newline — for subshells, curl, and shell scripts:

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

Requires belt login first (or INFSH_API_KEY set in the environment). When not logged in, errors go to stderr and stdout stays empty.

What you can do

Development

Running Apps

When an app is missing required secrets or integrations, infsh app run (and belt agent run) prints categorized setup hints instead of a generic API error — for example belt secrets set <KEY> <VALUE> or belt integrations connect <provider>. MCP requirements suggest belt mcp connect <slug>. The same requirement shape is returned by POST /run as HTTP 412 — see Check requirements.

Managing Apps

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

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

Pulled apps write namespace, name, and other metadata into inf.yml so deploy and run commands resolve the correct namespace/name ref.

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 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        # full descriptions from API (agent: true)

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

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. When stdin is hook JSON with transcript_path, belt prepends assistant text from the current turn (up to 1000 characters) before searching.

Use --agent to send agent: true in the suggest request body (full descriptions, no 200-rune truncation). Hook integrations installed via belt plugin init <agent> call belt suggest --json automatically.

Use infsh 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)

→ Connectors overview · Browsing connectors

Integrations (CLI)

List, connect, and inspect OAuth, service account, and MCP connections for your team:

1belt integrations list2belt integrations get google3belt integrations get mcp:mcp.linear.app --json   # includes integration id for agent tools4belt integrations connect google5belt integrations connect slack6belt integrations disconnect google

belt integrations connect looks up the provider in GET /integrations/configs, opens your browser for OAuth when needed, and polls for up to two minutes. 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.

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

Non-interactive OAuth (CI, scripts): When stderr is not a TTY, CI is set, or BELT_NON_INTERACTIVE=1, belt integrations connect prints the authorization URL but does not open a browser or poll. Open the URL manually, then verify with belt integrations get <provider>.

Provider keys match the REST API: google, google-sa, gcp, slack, mcp:mcp.linear.app, and so on. MCP servers use compound names (mcp:{hostname}) because each connection is a separate instance. Use belt integrations get --json when you need the integration id for agent connector tools.

→ Integrations API · Connectors overview

Flows (CLI)

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

Graph editing — belt flow edit applies draft mutations via POST /flows/{id}/actions:

1belt flow create --name voice-pipeline2belt flow edit node add abc123 tts --app elevenlabs/tts3belt flow edit node set-input abc123 tts text "hello world"4belt flow edit node set-input abc123 voice-changer audio --from tts:audio5belt flow edit output set abc123 audio --from voice-changer:audio6belt flow describe abc1237belt flow run abc123 -f8belt flow publish abc123

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 init <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.

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 — the same upsert behavior as infsh app deploy. The namespace is assigned from your logged-in team 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.

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. 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.

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.

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

Skills (CLI)

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.

→ Skill registry · Search concept · Search API

Knowledge (CLI)

belt know is an alias for belt knowledge. Refs use namespace/name or namespace/name@version-id (same as the REST API). The CLI sends X-API-Version: 2 on API calls automatically.

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 reference

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.

→ Knowledge API · Creating skills

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: discovery, use_case, feedback.

1belt feedback                                    # see what's pending2belt feedback discovery "found it on github"3belt feedback use_case "building AI agents for customer support"4belt feedback "love the speed, wish there were more templates"

After most commands, the CLI may show one unanswered question in the tips area (stderr). Each question has its own 72-hour cooldown; after you answer one, the next unanswered question appears on the following command. When all three structured questions are answered, a one-time freeform prompt suggests belt feedback "...".

The same questions can appear in coding-agent hook context via belt suggest --json — agents can run belt feedback on your behalf. 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 or --json). When you submit feedback, the last five entries are sent as context.

Suppress survey prompts and other stderr tips with INFSH_NO_TIPS=1.

→ Survey API · Coding agents — hook context

Tasks (CLI)

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

JSON output (--json)

Many commands accept --json for machine-readable output (belt task get, belt agent list, belt chat send, and others). belt me --json is an exception: it prints the API payload on success but does not emit a JSON error object on failure.

On failure with --json active, the CLI writes a JSON error object to stdout in addition to the human-readable message on stderr:

1{"error": "not logged in or session expired. run 'belt login' to authenticate"}

Parse stdout for automation; ignore stderr unless you need the formatted message. Successful --json responses use the command-specific schema documented in each command's help (belt task get --help).

Billing and plan limits

Billing and plan-limit errors include upgrade URLs in the error string when the API returns entitlement metadata (upgrade_available: true).

Inspect usage programmatically with GET /entitlements/usage — see Entitlements API.

→ Billing API · Subscription API · Troubleshooting — Plan limits

Environment Variables

Shell Completions

1infsh completion bash  # or zsh, fish, powershell

Next

→ Coding Agents — Build with AI assistants

→ Creating an App — Manual setup