Auxot
Tutorials Docs Pricing Login

Connect a CLI provider (Claude Code, Cursor, Codex)

Wire your CLI tool of choice — Claude Code, Cursor, or OpenAI Codex CLI — to use Auxot as its AI backend, so terminal sessions go through your governance, your context files, and your routing.

Plus: three Admin-Agent prompts you can paste — an agent UUID starter prompt drafted from your roster, a CLI auth troubleshooting list ordered by likelihood, and an Admin-Agent walkthrough of audit-log routing once real CLI traffic shows up.

Audience Developers
Time ~10 min
Prerequisites An Auxot account on any tier. A Personal API Key ([Generate your first API key](/tutorials/generate-your-first-api-key)) or a Team API Key ([Create a shared Team API Key](/tutorials/create-a-team-api-key)). One of the supported CLI tools installed locally: Claude Code, Cursor, or OpenAI Codex CLI.
You'll end up with CLI pointing at Auxot OpenAI-compat base URL plus API key smoke-tested — optional agent UUID wired so terminals inherit governance instead of slipping past shared context files.

When a tutorial shows italic text in quotation marks, it usually mirrors a label or helper string inside Auxot. Product copy changes between releases — if something reads differently in your workspace, trust what you see on screen.

Callouts with a Worth knowing gold accent are meant as must-read context before you move on. Blockquotes that open with Tip are lighter, optional depth.

Why this matters

When you use a CLI like Claude Code or Cursor, by default it talks directly to the AI provider (Anthropic, OpenAI, whoever) using whatever account those tools are configured with. Your prompts go straight to the model; nothing in between. That’s fine for personal exploration, but for team work, it means: no shared context files, no team-aware governance, no audit trail of what got asked, no per-team budgets, and no fallback routing if the provider has a bad day.

Pointing your CLI tool at Auxot instead routes everything through your governance layer. Same CLI experience, same models, but with team context attached, audit logs, and the ability to swap providers without touching your CLI’s config.

Same binary on disk: swapped base URL plus Auxot API key threads prompts through whichever model string or agent UUID you configure.

Quick start

Auxot exposes an OpenAI-compatible API endpoint, so any CLI tool that supports custom OpenAI base URLs can use it.

  1. Sign in: open Auxot in your browser and log in.
  2. Generate an API key: click Settings → API Keys, then + Create. Copy the key (Generate your first API key covers this in detail).
  3. Find your Auxot endpoint: it’s https://[your-auxot-server]/api/openai/v1 (or /api/openai; both work, Auxot normalizes the /v1 prefix).
  4. Open your CLI tool’s settings: Claude Code, Cursor, and Codex each have a settings file or env-var pattern for the OpenAI base URL and API key.
  5. Paste the endpoint and key, save, restart the CLI: your CLI is now talking to Auxot.

Done? Run any command in your CLI that calls the AI. Open Auxot’s System Health → Recent Activity in your browser: you should see the request appear there.

The agent can do that?

Terminal setup still happens on your laptop; paste your intent and any error output into Admin-Agent chat to sequence the steps. The proof is still the command you rerun after reloading env vars.

1. Script the proving prompt + default routing

Chat → Admin Agent:

I'm about to connect [Claude Code / Cursor / Codex] to Auxot. Looking at the agents I've already built, which one should the CLI route to by default — and what's the pattern of work I'd do in this CLI that the agent would handle well? Tell me what to type in my terminal as a first prompt that proves the routing works.

Why it’s non-obvious: Leaving the default model string sends you straight back to a generic completion API. Paste your workload context so replies suggest an agent UUID and a smoke prompt that actually exercises shared context files.

2. Triage pasted CLI stderr

Paste failures verbatim:

I'm trying to connect [CLI tool] to Auxot. I configured the base URL as [URL] and the API key. When I run a command, I get this error: [paste exact error]. What's likely wrong, and what should I check first?

Why it’s non-obvious: Identical error strings map to path typos, shells ignoring new exports, or model strings Auxot never registered: ordering hypotheses from pasted text beats toggling everything.

3. Review routing once real traffic shows up

After a few days of real use:

Look at the last week of API requests to my Auxot account from [the CLI's API key name]. Which models or agents has the CLI been hitting most? Are there patterns I should turn into a workflow? Is there work currently going to a generic model that should be going to one of my custom agents?

Why it’s non-obvious: Terminals that look fine can hide the fact that requests are still going to a generic model. Naming the API key and the time window forces pattern talk; promote repeats to Run a workflow or Create a Skill only after the audit-log evidence is there.

Go deeper

Why Auxot exposes an OpenAI-compatible endpoint

Most modern AI CLI tools (Claude Code, Cursor, Codex, Aider, and others) speak OpenAI’s API format because that became the de facto standard for “talk to a chat model.” Auxot accepts requests in that format at /api/openai/v1/chat/completions (or /api/openai/chat/completions; both paths work, Auxot normalizes the /v1/ prefix). When a CLI tool sends a request there, Auxot:

  1. Authenticates the API key.
  2. Looks at the model field: if it’s a model identifier (like gpt-4 or claude-3-7-sonnet-latest), Auxot routes the request to the right cloud provider. If it’s an Auxot agent UUID, the request goes through that agent’s full setup (Description, context files, tool policies).
  3. Streams the response back in OpenAI’s format.

The CLI tool doesn’t know it’s talking to Auxot. It thinks it’s talking to OpenAI.

CLI provider records in Auxot

In Settings → Providers, you can optionally create a CLI provider record (with cli_type of “claude” / “cursor” / “codex”). This is informational: it lets you label which CLI is connected, set an allowlist of models the CLI can use, and pick a default. It’s not required to make the connection work; it’s metadata for your own organization.

Troubleshooting

  • CLI can’t reach Auxot at all (connection refused). The CLI is configured with the wrong base URL. Check it’s /api/openai/v1 (or /api/openai), not /v1 alone or /api/v1.
  • 401 Unauthorized on every request. API key is wrong, expired, or you’re sending it in the wrong header. Most CLIs expect Authorization: Bearer [key]: Auxot accepts that.
  • 400 Model not found or similar. The CLI is sending a model name Auxot doesn’t recognize. Either change the CLI’s configured model to one Auxot has connected (see Settings → Providers) or use an Auxot agent UUID.
  • Requests succeed but the responses feel generic. The CLI is hitting Auxot’s auto-routing to a generic model, not one of your custom agents. Configure the CLI’s model parameter to an agent’s UUID to route through your Description + context files.

Variations & edge cases

  • Personal vs. Team API Key. Use a Personal Key (Generate your first API key) for your own CLI usage. Use a Team Key (Create a shared Team API Key) only if the CLI session represents the team’s work, not yours specifically. Personal keys are easier to revoke when you switch laptops or rotate credentials.
  • Local CLI tools that bundle their own AI providers. Some CLI tools (older Cursor versions, certain Codex variants) hardcode the provider; check their docs for whether the OpenAI base URL is configurable. If not, you can’t point them at Auxot.
  • Streaming vs non-streaming. Auxot supports both. Most CLI tools default to streaming for a smoother typing experience.
  • Free tier: CLI provider connections work the same as on paid tiers. Same OpenAI-compatible endpoint, same auth flow.
  • Audit log visibility. Every CLI request shows up in Audit Logs (View your audit logs), tagged with the API key that made it. Useful for figuring out what your CLI session is actually doing.

Walkthrough

Step 1: Generate an Auxot API key

Click Settings → API Keys, then + Create. Name the key after the tool that’ll use it: ”Claude Code on my work laptop” or ”Cursor on my dev machine.” Copy the full key (it starts with user. for personal, team. for team): you’ll only see it once.

If you’ve never generated an API key before, work through Generate your first API key. It covers naming, copying, and saving the key safely.

Step 2: Find your Auxot endpoint

Your endpoint is your Auxot server URL plus /api/openai/v1. For self-hosted Auxot, that’d be something like https://auxot.your-company.com/api/openai/v1. For Auxot Cloud, it’d be https://auxot.com/api/openai/v1 (or whichever cloud URL applies to your account).

The /v1 is OpenAI-compatible API versioning. Auxot also accepts requests at /api/openai (no /v1): they go to the same place.

Step 3: Configure your CLI tool

The exact location of the OpenAI base URL setting differs per CLI. Common ones:

  • Claude Code: uses the Anthropic Messages wire format. Set ANTHROPIC_BASE_URL to http(s)://HOST:PORT/api/anthropic/v1 and ANTHROPIC_API_KEY to your Auxot key (Claude Code & Cursor (Local)). Hands-on table and a curl bisect: Route Cursor and Claude Code through Auxot.
  • Cursor: open Cursor’s settings, find AI / Models / Custom OpenAI Base URL. Paste the Auxot endpoint there and the Auxot API key in the API key field.
  • OpenAI Codex CLI: set OPENAI_BASE_URL (or OPENAI_API_BASE depending on version) and OPENAI_API_KEY to your Auxot endpoint and key respectively.

Tip: Restart the CLI after changing config. Most CLIs cache the env vars at startup; they won’t pick up the new endpoint until the next launch.

Step 4: Pick which model or agent the CLI talks to

Most CLI tools let you choose a default model in their settings. Two options:

  • A connected AI model: type the model name (like gpt-4-turbo or claude-3-5-sonnet) that you’ve connected to Auxot via Settings → Providers. Auxot routes the request through that provider.
  • An Auxot agent: type the agent’s UUID as the model identifier. Auxot recognizes UUIDs and routes the request through the agent’s full setup (Description, context files, tool policies). This is where the value lives: your CLI now uses your custom agent instead of a generic model.

To find an agent’s UUID: Settings → Agents → click the agent → copy the UUID from the agent’s detail page URL or the copy-id button.

Step 5: Test it

Run any command in your CLI that calls the AI. Then open System Health → Recent Activity in your Auxot browser tab: you should see the request appear within a second or two, tagged with your API key’s name.

If nothing shows up: double-check the endpoint, the API key, and that the CLI actually restarted with the new config. (See Troubleshooting in Go deeper above.)

Step 6: (Optional) Register a CLI provider record in Auxot

Open Settings → Providers, click + Create Provider. Pick provider type CLI, then pick the CLI type (Claude Code, Cursor, or Codex). Name it after the user or workstation. This step is purely organizational: it doesn’t affect routing. It’s so when you look at your providers list later you can see “ah, that’s Claude Code on Sarah’s laptop.” Skip it if you don’t care about labels.

What’s next

Reference

Browse all tutorials