CLI overview
The oxagen CLI — an agentic coding tool for your terminal, powered by Oxagen's knowledge-graph context engine.
oxagen is an agentic coding tool that runs in your terminal. You give it a task in natural language and it reads your code, edits files, runs commands, and iterates until the task is done — the same loop you get from tools like Claude Code or Codex CLI, but grounded in Oxagen's knowledge-graph context engine: it can pull your workspace's knowledge graph into context so the agent reasons about your code, entities, and prior decisions, not just the files in front of it.
It also doubles as a thin client for the Oxagen platform: query the knowledge graph, manage workspace environments, and read or write the credential vault — all from the command line.
Who this is for
These docs are written for developers. You should be comfortable with a terminal, a package manager (npm/pnpm), and environment variables. No Oxagen-specific knowledge is assumed.
What you can do
- Code with the agent. Run
oxagenfor an interactive REPL, oroxagen "fix the failing auth test"for a one-shot run. The agent plans, edits, runs commands, and verifies. - Dispatch a fleet.
oxagen agents "migrate the billing module to the new schema"plans a goal into tasks and runs several agents in parallel, optionally each in its own git worktree. - Run models on-device. The agent's coordinator can run entirely on a local open-source code model — auto-provisioned and fit to your hardware — for a private, offline loop with no API key.
oxagen modelsmanages it; see On-device models. - Ground it in your graph.
oxagen graph pulldownloads an incremental snapshot of your workspace knowledge graph into a local replica; the agent uses it for context, andoxagen graph searchlets you query it directly. - Let it learn. The agent recalls workspace memory — lessons, conventions, and gotchas — before it acts, and records new ones as it works, so it gets better in your codebase over time.
- Manage your workspace. Inspect environments (
oxagen env) and the encrypted credential vault (oxagen secret) without leaving the shell. - Extend it. Define custom agents, slash commands, and hard-enforced rules as Markdown files in your repo, and connect external MCP servers to the loop.
Two credentials, two jobs
The CLI uses two independent credentials. Knowing which is which saves a lot of confusion:
| Credential | What it powers | How the CLI finds it |
|---|---|---|
AI_GATEWAY_API_KEY | The agentic coding loop — every model call the agent makes. This is your own Vercel AI Gateway key (bring your own key). Fallback: with only an ANTHROPIC_API_KEY, Claude models run directly against the Anthropic API (details). | Shell env → ~/.oxagen/settings.json (env.AI_GATEWAY_API_KEY) → gatewayKey in ~/.config/oxagen/config.json → nearest .env.local. |
| Oxagen platform token (+ org + workspace) | Platform commands that call api.oxagen.sh: graph, env, secret. This is an Oxagen API key (oxk_live_…) minted in the web app. | oxagen config token / OXAGEN_API_TOKEN, plus org and workspace. |
You can use the coding agent with just a gateway key — no Oxagen account required for the local loop. The platform token only matters once you want to pull your knowledge graph or touch workspace environments and secrets. And with an on-device coordinator you can go further still — running the agent with no gateway key at all, though cloud workers (for heavier code generation) will still need one.
Next steps
- Installation — get the
oxagenbinary onto your machine. - Account setup — create an Oxagen account and authenticate the CLI.
- Quickstart — your first agentic coding session.
- The agent engine — how a turn is planned, executed, and verified.
- Command reference and in-REPL slash commands — every command, both surfaces.