# @inference/cli Command-line interface for [Inference.net](https://inference.net) -- manage training runs, evals, datasets, and inferences from your terminal. ## Installation **Via npm (recommended):** ```bash npm install -g @inference/cli ``` **Via npx (no install):** ```bash npx @inference/cli --help ``` **Via Bun:** ```bash 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 ```bash # 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 ### Authentication ```bash 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 set-key # Set an API key for CI/headless use ``` ### Projects ```bash inf project list # List all projects inf project switch # Set the active project inf project current # Show the currently active project ``` ### Instrument (Automated Observability Setup) ```bash 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 ```bash inf training list # List training runs inf training get # Get details of a training run inf training logs # View training logs (-f to follow) inf training poll # Poll status until complete ``` ### Evals ```bash inf eval list # List eval run groups inf eval get # Get eval run group details inf eval rubrics # List rubrics inf eval datasets # List eval datasets ``` ### Datasets ```bash inf dataset list # List filtered datasets inf dataset get # Get dataset details inf dataset download # Download a dataset (-o output path) ``` ### Inferences ```bash inf inference list # List recent inferences inf inference get # Get full inference details ``` ### Traces ```bash inf trace list # List trace summaries inf trace get # Get trace summary + tree inf trace get --view tree # Render the span tree inf trace get --view timeline # Render a text waterfall inf trace get --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 # Inspect a trace export job inf trace export download # 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 ```bash inf span list # List spans inf span list --scope entrypoint # List entrypoint spans inf span list --trace-id --text foo # Search spans in a trace inf span get # Get span summary inf span get --view io # Print captured input/output inf span get --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 ```bash 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 ` | Override the active project for this command | | `--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://observability-api.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 | | ### 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://observability-api.inference.net` ## CI / Headless Usage For CI pipelines and automated environments where browser-based login is not possible: ```bash # 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.` | `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 1. Choose the next stable version. 2. Sync all committed CLI manifests to that version. ```bash 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` 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 - 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: ```bash 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