inf instrument hands your codebase to an AI coding agent (Claude Code, OpenCode, or Codex) to wire up Catalyst observability for you. It scans your project, finds your LLM clients — OpenAI, Anthropic, LangChain, Gemini, Groq, Cerebras, OpenRouter, and others — and rewrites them to route through the Inference.net gateway so every call is captured in Observe.
This is the fastest way to connect an existing app to Catalyst. You don’t need to know the SDK changes in advance — the agent figures it out from your code.
Prerequisites
- A signed-in CLI session.
inf instrument requires a session login — API-key auth is rejected. Run inf auth login first.
- A supported AI coding agent on your
PATH. Install one of:
inf instrument
Instrument the current working directory. The command walks you through:
- Confirming the target project (auto-selected if you only have one).
- Fetching your project’s default API key.
- Detecting installed coding agents and picking one (prompted if you have more than one).
- Downloading the instrumentation skill and building the agent prompt.
- Launching the agent interactively so you can review and approve the changes.
cd /path/to/your/project
inf instrument
Options
| Flag | Required | Description | Default |
|---|
--dry-run | No | Ask the agent to preview changes without modifying files | Off |
--agent <name> | No | Preselect the coding agent by binary name: claude, opencode, or codex. Skips the interactive picker — useful in CI, scripts, or when driving inf instrument from another agent | Prompt |
-y, --yes | No | Skip the “Instrument this project?” confirmation | Off |
--print-prompt | No | Fetch the instrumentation skill, build the full agent prompt, print it to stdout, and exit without spawning an agent. Lets another orchestrator (your own agent harness, a CI job) drive the agent itself | Off |
--task-id <id> | No | Default task id the agent tags every call with via the x-inference-task-id header. inf inference list --task … and inf dataset create --task … filter on this. 1–64 alphanumeric chars plus ._:- | default |
What the agent does
Once the agent launches, it:
- Scans your codebase for LLM clients (OpenAI, Anthropic, LangChain, Gemini, Groq, Cerebras, OpenRouter, and others).
- Redirects base URLs to the Inference.net gateway.
- Adds routing headers so requests are authenticated, forwarded, and traced.
- Tags every call with the default
x-inference-task-id so call sites group automatically in Observe.
- Shows you a diff before applying changes.
Your app keeps using the same provider SDKs it already has — inf instrument rewrites the client construction, not your call sites.
Examples
# Preview what would change without touching any files
inf instrument --dry-run
# Use Claude Code non-interactively (skip the agent picker and the confirmation)
inf instrument --agent claude --yes
# Tag every instrumented call with a custom task id for filtering later
inf instrument --task-id support-chatbot
# Print the prompt for your own agent orchestrator instead of spawning one
inf instrument --print-prompt > instrument-prompt.md
Verify instrumentation
After the agent finishes, run your app to generate a few LLM calls, then confirm they’re captured:
Or open the observability dashboard link the command prints on completion.
Supported providers
Built-in: OpenAI, Anthropic.
OpenAI-compatible via x-inference-provider-url: Google Gemini, Together AI, Groq, Fireworks AI, Mistral AI, Cerebras, Perplexity, DeepSeek, OpenRouter, Azure OpenAI, and any OpenAI-compatible endpoint.
Troubleshooting
inf instrument now requires a session login. Unset INF_API_KEY and run inf auth login.
The command refuses to run with INF_API_KEY set in your environment. Unset it and sign in with inf auth login — instrumentation needs your session to fetch the project’s default API key on your behalf.
No supported AI coding agent found.
Install one of Claude Code, OpenCode, or Codex from the links in Prerequisites. inf instrument detects the binary on your PATH.
--agent <name> is not installed (or not supported).
The binary name must match exactly: claude, opencode, or codex. Check which claude (or the name you passed) resolves to an executable.
No default API key found for project …
Open the dashboard → the relevant project → API Keys and create one. inf instrument needs a project-scoped key to embed in the agent prompt.
The agent exited with an error.
inf instrument prints the dashboard URL for manual integration on failure. You can also rerun with -v to see debug output, including the skill URL and prompt length.
