@inference/cli

Command-line interface for Inference.net -- manage training runs, evals, datasets, and inferences from your terminal.

Installation

Global install (npm, Bun, pnpm, or Yarn Classic):

npm install --global @inference/cli
bun install --global @inference/cli
pnpm add --global @inference/cli
yarn global add @inference/cli

Run inf update to update a supported global installation through the package manager that installed it (npm, Bun, pnpm, or Yarn Classic v1 — Yarn Berry v2+ is not supported because it removed yarn global). It prints the version it replaced; run inf --version afterward to confirm the new version. Project-local installs should be updated through that project's package manager. npx and bunx fetch a current release when you run them, so rerun the command instead of using inf update. Windows global installs are not yet supported by inf update — rerun your package manager's install command to update.

Via npx (no install):

npx @inference/cli --help

Via Bun:

bunx @inference/cli --help

Supported Platforms

| Platform | Architecture | Package | | -------- | --------------------- | ----------------------------- | | macOS | Apple Silicon (arm64) | @inference/cli-darwin-arm64 | | macOS | Intel (x64) | @inference/cli-darwin-x64 | | Linux | x64 | @inference/cli-linux-x64 | | Linux | arm64 | @inference/cli-linux-arm64 |

The correct binary is installed automatically based on your platform.

Quick Start

# Sign in via browser
inf auth login

# List your projects
inf project list

# Select a project
inf project switch

# Instrument a codebase with observability (run from your project directory)
inf instrument

# View recent training runs
inf training list

# Launch interactive dashboard
inf dashboard

Commands

REST-backed subcommands. Several resource groups below (e.g. project, api-key, dataset, deployment, eval, models, signal, team) carry additional subcommands generated from the platform's REST API, alongside the hand-written ones documented here. Run inf <group> --help to see the full, current list for a group — a hand-written command always takes precedence over a generated one of the same name. The same operations are available as a REST API (/api/rest, with Swagger docs at /api/rest/docs) and as MCP tools.

Authentication

inf auth login          # Sign in via browser (device authorization flow)
inf auth logout         # Sign out and clear stored credentials
inf auth status         # Show current authentication status
inf auth whoami         # Show which user and team the CLI is currently authenticated as
inf auth set-key <key>  # Set an API key for CI/headless use

Projects

inf project list        # List all projects
inf project switch [id] # Set the active project, or choose one interactively
inf project current     # Show the currently active project

Team Management

A team is 1:1 with an organization on Inference.net. Commands that talk to the API scope to a team via a request header, so switching teams is a local, instant operation — no re-authentication required.

inf team list                              # List teams you belong to (marks the active one)
inf team current                           # Show the currently active team
inf team switch [id-or-slug]               # Set the active team, or choose one interactively
inf team create <name>                     # Create a team (and default project); both become active
inf team invite <email>                    # Invite a member to the active team
inf team invite <email> --role admin       # Invite as admin (default role: member)

Team management commands (list, current, switch, create, invite) require session auth via inf auth login, not an API key. inf team switch <id-or-slug> is the one place slugs/names get resolved (it fetches your team list first) — the global -t, --team <id> flag and INF_TEAM_ID only accept a real team ID, since they skip that lookup for speed.

API Key Management

inf api-key create <name> --project <id>                 # Create a project-scoped key (defaults: active project, read+write)
inf api-key create <name> --project <id> --permissions read  # Read-only key
inf api-key create <name> --project <id> --team <id>     # Create under a specific team
inf api-key list                                         # List keys for the active team
inf api-key list --team <id>                             # List keys for a specific team
inf api-key revoke <id>                                  # Revoke a key
inf api-key revoke <id> --team <id>                      # Revoke under a specific team

The raw key value is shown only once, at creation — save it immediately.

Instrument (Automated Observability Setup)

inf instrument             # Instrument your codebase with Catalyst observability
inf instrument --dry-run   # Preview changes without modifying files

Automatically instruments your codebase to route LLM API calls through the Inference.net observability proxy. The command:

1. Confirms your active project and API key
2. Detects available AI coding agents (Claude Code, OpenCode, or Codex)
3. Fetches the latest instrumentation skill from inference.net
4. Launches the selected agent to scan and modify your code

Run this from the root of the project you want to instrument.

Training

inf training list              # List training runs
inf training get <id>          # Get details of a training run
inf training logs <id>         # View training logs (-f to follow)
inf training poll <id>         # Poll status until complete

Evals

inf eval list                  # List eval run groups
inf eval get <id>              # Get eval run group details
inf eval rubrics              # List rubrics
inf eval datasets              # List eval datasets

Datasets

inf dataset list               # List filtered datasets
inf dataset get <id>           # Get dataset details
inf dataset download <id>      # Download a dataset (-o output path)

Inferences

inf inference list             # List and filter inferences
inf inference facets           # Probe valid filter values + full filter reference
inf inference get <id>         # Get the full stored request + response (method, path, headers, bodies)

# Search / sort (no need to hardcode filter values — discover them with `facets`):
inf inference list --sort input_tokens --order desc --limit 50  # largest prompts first
inf inference list --filter inputTokens>39000                   # numeric filter
inf inference list --model my-model --status 200 --range 7d     # array + time filters
inf inference list --metadata user_id=abc123                    # metadata filter

# Paginate from a script — JSON output includes nextCursor:
cursor=$(inf --json inference list --sort input_tokens --order desc | jq -r '.nextCursor')
inf --json inference list --sort input_tokens --order desc --cursor "$cursor"

# Fetch the complete bodies for scripting / archiving:
inf --json inference get <id>                      # Full payload as clean JSON (pipe to jq)
inf --json inference get <id> | jq '.response.body' # Just the response body
inf inference get <id> --response --body           # Raw response body (no decoration)
inf inference get <id> --request --body -o req.json # Dump the raw request body to a file
inf --json inference get <id> -o dump.json         # Save the full {request,response} payload

The full bodies are returned only when payload storage was enabled for the request — otherwise request/response come back null.

Traces

inf trace list                                  # List trace summaries
inf trace get <trace-id>                        # Get trace summary + tree
inf trace get <trace-id> --view tree            # Render the span tree
inf trace get <trace-id> --view timeline        # Render a text waterfall
inf trace get <trace-id> --view thread          # Render captured conversation messages
inf trace facets                                # Inspect filter facets and counts
inf trace export create --range 1d --kind LLM   # Queue a JSONL trace export
inf trace export list                           # List trace export jobs
inf trace export status <job-id>                # Inspect a trace export job
inf trace export download <job-id>              # Download a ready export

Trace list and facet commands support the same dashboard filter vocabulary: --range, --from, --to, --kind, --provider, --model, --service, --environment, --user, --session, --agent, --status, --filter, --metadata, and --resource.

Spans

inf span list                                   # List spans
inf span list --scope entrypoint                # List entrypoint spans
inf span list --trace-id <trace-id> --text foo  # Search spans in a trace
inf span get <trace-id> <span-id>               # Get span summary
inf span get <trace-id> <span-id> --view io     # Print captured input/output
inf span get <trace-id> <span-id> --view attributes
inf span facets                                 # Inspect span filter facets

Span list and facet commands support trace filters plus --trace-id, --text, and --scope all|root|entrypoint.

Dashboard

inf dashboard                  # Launch interactive TUI dashboard

The dashboard provides a tabbed interface for browsing training runs, evals, datasets, and inferences. Use 1-4 to switch tabs, j/k to navigate, Enter to drill down, r to refresh, and q to quit.

Global Options

| Flag | Description | | -------------------- | --------------------------------------------------- | | --json | Output results as JSON (useful for scripting) | | -v, --verbose | Enable verbose debug output | | -p, --project <id> | Override the active project for this command | | -t, --team <id> | Override the active team for this command (team ID) | | --version | Show the CLI version | | --help | Show help |

Configuration

Config File

Stored at ~/.inf/config.json. Managed automatically by inf auth commands.

Environment Variables

| Variable | Description | Default | | ---------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------- | | INF_API_URL | LLM Ops API base URL | https://relay.inference.net | | INF_AUTH_URL | Auth server base URL | Derived from API URL | | INF_UI_URL | Web app URL (for device auth) | Derived from API URL | | INF_API_KEY | Scoped platform key for headless/CI auth | | | INF_PROJECT_ID | Override the selected project when a key can access multiple projects | | | INF_TEAM_ID | Override the active team (team ID; use inf team switch <id-or-slug> to resolve a slug/name once) | | | INF_CONFIG_DIR | Override where ~/.inf/config.json is stored (primarily for test isolation) | ~/.inf |

Priority Order

Authentication resolves in this order:

1. INF_API_KEY environment variable
2. API key in config file (inf auth set-key)
3. Session token in config file (inf auth login)

API URL resolves in this order:

1. INF_API_URL environment variable
2. apiUrl in config file
3. Default: https://relay.inference.net

CI / Headless Usage

For CI pipelines and automated environments where browser-based login is not possible:

# Set your API key (obtain from Inference.net dashboard under project settings)
# New keys use the sk-inference-* prefix. Existing sk-observability-* keys still work.
export INF_API_KEY=sk-inference-...

# Or persist it in the config file
inf auth set-key sk-inference-...

# Set the project when the key is scoped to multiple projects.
# Single-project keys or keys with a default project can omit this.
export INF_PROJECT_ID=your-project-id

# Now all commands work without interactive login
inf training list --json

Release Workflow

INF-CLI is published to npm entirely through GitHub Actions.

• Workflow: .github/workflows/inference--inf-cli-release.yml
• Packages published together:
  • @inference/cli
  • @inference/cli-darwin-arm64
  • @inference/cli-darwin-x64
  • @inference/cli-linux-x64
  • @inference/cli-linux-arm64
• Version source of truth: inference/apps/inf-cli/package.json
• The checked-in version must always be a stable semver like 0.0.9
• Do not commit prerelease versions like 0.0.9-beta.3 to git

Branch Mapping

| Branch | Environment | Published Version Format | npm Dist-Tag | | ------------- | ----------- | ------------------------ | ------------ | | development | Beta | 0.0.9-beta.<run> | beta | | main | Stable | 0.0.9 | latest |

Developers publish across environments by moving the same stable base version through development first, then main.

What The Workflow Does

On a qualifying push or manual dispatch, the workflow:

1. Validates that the run is on development or main
2. Reads the stable base version from apps/inf-cli/package.json
3. Computes the publish version for the target environment
4. Runs INF-CLI unit tests and bun run tsc
5. Builds the umbrella CLI plus all four platform binaries
6. Creates a staged publish artifact and rewrites package versions only inside staging
7. Validates each staged package with npm pack --dry-run
8. Publishes platform packages first and @inference/cli last
9. Retries npm verification until the expected version and dist-tag are visible

The workflow can also repair a partial stable release. If @inference/cli already exists on npm but one of the platform packages is missing, rerunning the workflow on the same stable version will publish only the missing packages.

Releasing A New Version

Option A — Auto-bump from CI (recommended)

Trigger the workflow manually and let CI bump the version for you:

1. Run workflow_dispatch on the branch you want to release from (development for beta, main for stable).
2. Set semver_action to patch, minor, or major.
3. The bump-version job runs npx semver -i, then scripts/sync-versions.ts so the main package and all four platform manifests move together, commits the result, and pushes a release-inf-cli-<version>-<sha> tag back to the dispatched branch.
4. The same run then builds and publishes the bumped version.

Leave semver_action=none (the default) to publish the already-committed version without bumping.

Option B — Bump manually

1. Choose the next stable version.
2. Sync all committed CLI manifests to that version.

cd inference/apps/inf-cli
bun scripts/sync-versions.ts 0.0.9

3. Commit the manifest changes.
4. Merge or push that version to development to start the beta train.
5. Validate the beta release from npm using the beta dist-tag.
6. Merge the same version to main to publish the stable release to latest.

Manual Runs

• workflow_dispatch takes a semver_action input (none/patch/minor/major); anything other than none bumps, commits, and tags the new version on the dispatched branch before publishing
• workflow_dispatch with dry_run=false always attempts a publish on development or main
• Set dry_run=true to validate the full build and packaging path without publishing to npm; a dry run computes and builds the bumped version but does not push the bump commit or tag, so it stays side-effect-free
• Pushes to development always publish a fresh beta release when this workflow is triggered
• Set dry_run=false only on development or main
• Manual runs from other branches are rejected by the workflow

Local Release Preview

If you want to verify the compiled CLI version locally without changing committed manifests, you can inject a temporary build version:

cd inference/apps/inf-cli
INFERENCE_CLI_BUILD_VERSION=0.0.9-beta.local bun run build:npm:all
./bin/inf --version

This is useful for previewing beta-style binaries before the GitHub Actions workflow publishes them.

License

MIT