CLI quickstart

This walkthrough assumes you have installed the CLI and authenticated it. Run the commands from the root of a project whose agents you govern.

1. Link the projectCopy Anchor Link

oxagen init

init resolves an org and workspace (it asks you to pick when you belong to more than one) and writes .oxagen/workspace.json. Every other command reads that file to scope itself, so you don't pass --org or --workspace each time.

It then checks whether the workspace has a GitHub connection and offers to create one, so the knowledge graph has a source to ground on. Running init again reuses the existing link instead of asking again.

Name the org and workspace to link without a prompt, for example in CI:

oxagen init --org acme --workspace payments

If your workspace's steering repo still holds an .oxagen/ tree, write it into this directory's .oxagen/:

oxagen pull

A steering repo in the current layout keeps its steering records under steering/, so skip this step for one.

2. Check the spend ceilingCopy Anchor Link

oxagen budget show

This prints each configured spend ceiling (the org's and the active workspace's) with its live burn: period-to-date spend, the projection to the end of the period, and whether the admission gate is denying requests now.

Set one. An organization Owner or Compliance and Billing member can set either ceiling, and a workspace Admin can set that workspace's own:

oxagen budget set --scope workspace --period monthly --limit 500

See Spend budgets for the threshold ladder and the rolling-window form.

3. Price a workload before it runsCopy Anchor Link

oxagen cost makes no network call. It prices token counts against the rate card built into the CLI:

oxagen cost --in 200000 --out 40000

With no --model, it compares every priced model, cheapest first, and reports the spread. Add -m <slug> for one model, or --rates to print the card.

4. Explain what an agent didCopy Anchor Link

Given a run id, oxagen run turns lists each turn with its model and tool steps, tokens and cost. oxagen run transcript prints what the agent did:

oxagen run turns tse_01J8…
oxagen run transcript tse_01J8…

5. Ground a question in the graphCopy Anchor Link

oxagen graph search -q "where do we enforce tenant isolation?" -n 5

The query runs online and returns only the bounded results your workspace grants allow. There is no local copy of the workspace graph. See Knowledge graph from the CLI.

6. Curate what agents have learnedCopy Anchor Link

oxagen memory list                                   # ranked by how often runs used them
oxagen memory show mem_01J8…
oxagen memory promote mem_01J8… --kind code-rule --force must
oxagen memory dismiss mem_01J9… --reason covered

A promoted memory becomes a steering record on the memory PR, and it steers other agents once the PR merges. See Memory from the CLI.

7. Manage environments and secretsCopy Anchor Link

oxagen env list
oxagen secret list                       # masked metadata only
oxagen secret set DATABASE_URL "postgres://…" --env staging
oxagen secret reveal DATABASE_URL --env staging   # recorded to the access log

Next stepsCopy Anchor Link

• Command reference: every command and flag.
• Spend budgets: the ceilings that gate agent runs.
• Memory from the CLI and Knowledge graph from the CLI: the two grounding surfaces.