CLI

The oxygen CLI is the portable execution surface for Oxygen. Use it to authenticate, select an organization, create and inspect tables, import data, add columns, run bounded enrichment, inspect runs, connect integrations, and check credits.

MCP tools call the same API contract. The web app shows the state created by CLI and MCP commands.

Install, update, and authenticate

npm install -g @oxygen-agent/cli
oxygen login
oxygen status --json
oxygen update

For non-interactive environments:

oxygen api-keys create --name "automation key" --json
oxygen auth use-token --token <token> --json

Use oxygen for production workspaces at https://oxygen-agent.com. oxygen-dev is for Oxygen developers testing the dev deployment and should not be used for customer production workspaces unless a developer guide explicitly tells you to.

Profiles and orgs

oxygen profiles list --json
oxygen profiles use <profile> --json
oxygen orgs list --json
oxygen orgs use <organization-slug> --json
oxygen whoami --json

Agencies usually keep one organization per client. The active org scopes tables, context, integrations, runs, and credits.

Command groups

Group	Common commands
Auth	`login`, `logout`, `status`, `update`, `api-keys create`, `auth use-token`, `profiles list/use/current`
Orgs	`orgs list`, `orgs use`, `orgs select`, `orgs billing-link`, `orgs billing-unlink`
Context	`whoami`, `onboarding start`, `context resolve`, `context profile get/update`, `context assets list/get/upsert/archive`
Tables	`tables create`, `list`, `describe`, `preview`, `query`, `insert`, `upsert`, `update`, `delete-row`, `import`, `export`, `duplicate`, `rename`, `archive`
Columns	`columns add`, `run`, `materialize`, `rerun`, `rename`, `update`, `retype`, `archive`, `action-column add-provider`
Enrichment	`enrich-column preview`, `enrich-column run`, `companies enrich preview/run`, `enrichment apply-default-cascade`
Runs	`runs list/get`, `table-runs create/list/get/items/wait/provider-summary/pause/resume/cancel/retry-failed`, `table-ingestions create-tool-page/get/items/wait/cancel/retry-failed`
Tools	`tools search`, `tools get`, `tools enums list/get`, `tools run`
Integrations	`integrations list`, `connect`, `disconnect`, `actions`, `run`, `events list/enable/disable/deliveries`
Workflows	`workflows schema`, `lint`, `apply`, `list`, `get`, `call`, `events emit`, `runs`, `run`, `tail`, `cancel`, `enable`, `disable`
Blueprints	`blueprints list`, `describe`, `preflight`, `apply`, `export`, `save`, `share`, `marketplace`
Billing	`billing balance`, `billing usage`
Observability	`observability events`, `rows history`, `cells inspect`, `cells history`
Agent skills	`skills list`, `skills doctor`, `skills install`

Run oxygen <command> --help for the exact flags. Add --json when an agent, script, or automation needs structured output.

Table-first examples

Create a table:

oxygen tables create "Q1 TAM" \
  --columns-json '[{"label":"Company Domain","key":"domain","data_type":"text","semantic_type":"company_domain"},{"label":"Company Name","key":"company_name","data_type":"text"}]' \
  --json

Import data:

oxygen tables import q1-tam --file accounts.csv --upsert-key domain --background --json
oxygen tables preview q1-tam --limit 10 --json

Add and pilot a provider-backed column:

oxygen tools get blitzapi.person_enrich --json
oxygen tools run blitzapi.person_enrich \
  --input-json '{"person_linkedin_url":"https://www.linkedin.com/in/example"}' \
  --mode dry-run \
  --json
oxygen columns add q1-tam \
  --label "Person Enrichment" \
  --key person_enrichment \
  --kind tool \
  --data-type jsonb \
  --definition-json '{"version":1,"mode":"native","toolId":"blitzapi.person_enrich","inputMapping":{"person_linkedin_url":{"type":"column","columnKey":"linkedin_url"}}}' \
  --json
oxygen table-runs create q1-tam --column person_enrichment --limit 1 --max-credits 1 --json

Scale a paid run only after the pilot output, row scope, and credit ceiling are clear:

oxygen table-runs create q1-tam --column person_enrichment --limit 100 --max-credits 100 --json
oxygen table-runs get <run-id> --json
oxygen table-runs items <run-id> --status failed --json

Output shape

State-bearing commands accept --json and return an envelope:

{
  "ok": true,
  "data": {
    "web_url": "https://oxygen-agent.com/tables/table_123"
  },
  "meta": {
    "command": "tables preview",
    "version": "1.138.0",
    "minimum_cli_version": "1.135.0"
  }
}

Use data.web_url to inspect the result in the web app. The exact data shape depends on the command, but run-oriented commands include run ids, status, item counts, credits, and error summaries when available.

Safety posture

Dry-run and preview commands do not spend credits or write externally. Paid provider calls, AI columns, enrichment runs, CRM writes, outbound enrollment, and LinkedIn actions should be run only after a human has reviewed the row scope and credit ceiling.

Use these patterns:

oxygen tools run <tool-id> --input-json '{...}' --mode dry-run --json
oxygen enrich-column preview <table> --capability work_email --limit 10 --json
oxygen enrich-column run <table> --capability work_email --limit 100 --max-credits 100 --json
oxygen workflows templates run <template-id> --input-json '{...}' --mode live --max-credits 100 --approved --json

Unused reserved credits are not spent. Inspect final usage with:

oxygen billing balance --json
oxygen billing usage --limit 50 --json