# Oxy CLI

> Use when you need data out of an Oxy deployment — querying a customer's warehouse or semantic layer, reading threads/runs/apps/orgs, checking why an endpoint 4xxs, or reproducing a customer-reported bug against real data. Also when you need to know which endpoints exist or what body one takes, and (staff) when standing a new customer account up or checking which of its steps have landed. Triggers on "query the customer's data", "what does this API return", "debug this in production/dev", "which endpoint", "check the thread/run/app", "oxyc", "oxy api", "stand up a new customer", "new account setup", "oxyc bootstrap".

- Skill: `oxy-hq/oxy-cli` (Agent Skill)
- Install (CLI): `npx get-skill add oxy-hq/oxy-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oxy-hq/oxy-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: oxy-hq (https://skillmd.com/u/oxy-hq)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/oxy-hq/oxy-cli

---


# Getting data out of Oxy with `oxyc`

`oxyc` is an authenticated `gh api`-shaped client. Prefer it over `curl` — it
resolves the token, picks the right credential for the surface, and can tell
you what endpoints exist.

```bash
npm i -g @oxy-hq/cli    # or: npx @oxy-hq/cli <command>
oxyc <command>

# From a checkout instead, when you want the build in your working tree:
node <repo>/sdk/cli/dist/main.mjs <command>
```

## The loop that works

**Never guess a path.** Three commands, in this order:

```bash
oxyc routes sql                            # 1. what exists, and what it does
oxyc schema {workspace}/sql/query          # 2. the body it expects
oxyc api {workspace}/sql/query \
  -f 'sql=select 1' -f database=<name> --md   # 3. call it
```

To get data out of a customer's warehouse, that is the whole path:

```bash
oxyc api orgs --md                                  # org ids
oxyc api {org}/workspaces --md                      # workspace ids
oxyc api {workspace}/databases --jq '.[].name'      # connection names
oxyc api {workspace}/sql/query -f 'sql=…' -f database=… --md
```

`oxyc routes <filter>` matches on method, path, surface and description, so
`oxyc routes query`, `oxyc routes admin`, `oxyc routes semantic` all work. Run
it with no filter only when you genuinely want all ~670 — it is a lot of
context.

## Placeholders — do not hunt for ids

`{org}`, `{workspace}`, `{project}`, `{customer}` and `{me}` fill themselves
from the customer repo you are standing in, or from `--org` / `--workspace` /
`--project`.

```bash
oxyc api {org}/workspaces --md      # find a workspace id
oxyc api {workspace}/agents
```

An unresolved placeholder errors and names the flag that would fill it. It is
never sent to the server as a literal.

## Keep the context small

- `--jq '<expr>'` on the server-side shape, **always**, before you look at a
  large response. Dumping a full thread list into context is the common waste.
  It needs no `jq` on PATH (oxyc embeds jq), so use it in CI and cloud VMs too.
- `--md` turns an array of objects into a markdown table — far fewer tokens
  than the same rows as JSON, which repeats every field name per row.
- `--cache 5m` when you are walking the same endpoints repeatedly.
- `--paginate` merges every page into one document. It is a heuristic on this
  API (pagination is not uniform); if a result looks short, pass
  `--paginate-key <field>`.

## Beyond the API

    oxyc validate                  # check the workspace YAML — no network, no token
    oxyc proxy --env dev           # local app dev against cloud data
    oxyc experiments list          # experiments: draft, price, register, status, interim, abort, result
    oxyc flags list                # feature flags: kill switch, per-org overrides, A/B splits (staff)
    oxyc login-link --next /ide    # one-time URL that signs a browser in as your token
    oxyc workspace clone <id>      # clone the workspace's repository to edit locally; push to deploy
    oxyc guide                     # this page, to paste into a context file

`oxyc workspace clone <workspace-id>` is how you change a workspace: authoring
happens in its repository, not in the product. It runs your own `git clone` (no
token injected), prints the path of the workspace folder (the repository's
subdirectory when the workspace lives in one), and opens it in VS Code or Cursor
only from an interactive terminal (`--open code|cursor|none`; an agent gets the
command printed instead). Edit, commit, push: **a push to the default branch
compiles and deploys**; to try a branch first, `oxyc preview create <branch>
--workspace <id> --wait` (staff). Exit `5` means the workspace has no repository
yet (connect one in Settings), `6` a failed `git clone`, `8` a non-empty `--dir`.

`oxyc validate` is the one command that works entirely offline. It checks
`config.yml`, `.automation.yml`, `.agentic.yml` and
`.agent.test.yml` against the schemas the Rust config types generate. It is
STRUCTURAL only — `oxy validate` additionally checks an automation's
`database:` names against `config.yml`, but it too is structural for
`.agentic.yml` (`databases:` and `llm.ref` are not resolved), so an agent both
accept can still fail at run time.

To look at a deployed environment in a browser, navigate your browser tool to
`$(oxyc login-link --env dev --next /ide)`. It is a one-time link that signs
the browser in as your token — no OAuth, no inbox — and it needs a personal
access token: an agent token (below) is one, and so is what `oxyc login` stores.

If your runtime speaks MCP, `oxyc mcp` serves the same API surface as four
tools (`oxy_routes`, `oxy_schema`, `oxy_request`, `oxy_whoami`) instead. It
reads its credential from `OXY_TOKEN` only — with the variable unset it exits
`4` rather than using the machine's `oxyc login`; `oxyc mcp --login` opts
into that. The same holds for any command given `--token-env <VAR>`.

## Feature flags (staff)

Use `oxyc flags` to turn an Oxy product change on for named orgs, run an A/B split, or
see what a flag serves an org — instead of the admin page or hand-written PATCHes.
Flags are declared in code; you change the kill switch and the targeting rules, never
create a flag. **Every write is prod-affecting** (`--env` defaults to production) and
asks first; pass `--yes` when there is no terminal, after `--dry-run` shows the rules.

    oxyc flags list | show <key>                       # read: rules, unit, scope
    oxyc flags eval --org acme [--user <uuid>]         # preview what each flag serves them
    oxyc flags set <key> --off --yes                   # kill switch: off = every org gets the first variant
    oxyc flags rules <key> --set-org acme=treatment --yes      # add one override, keep the rest
    oxyc flags rules <key> --split control=50,treatment=50 --yes   # percent, must total 100
    oxyc flags rules <key> --file rules.json | --clear --yes

Orgs take a slug or UUID, users a UUID. Rules on a flag with `per_org: false` are refused
(422, exit 6), and rules saved behind an off kill switch do not apply until `set --on`.
Treat a running split as immutable. `oxyc flags org <org>` is what a member of that org
sees.

## Standing a customer up (staff)

`oxyc bootstrap` is the sequence a new customer account goes through, and the part of
it a command can do. **Staff only, and it says so rather than failing oddly:** most
phases read or write the admin surface, creating the organization needs the
org-creation capability, and the subscription phase is the Global Owner's alone. A
customer's own agent cannot run this and should not try.

    oxyc bootstrap plan   <customer> [--crews]        # the whole sequence; reads nothing, writes nothing
    oxyc bootstrap run    <customer> --owner <email>  # do the phases oxyc can, print the rest
    oxyc bootstrap verify <customer> [--json]         # which phases have landed

Shared flags: `--name <display>`, `--repo <owner/repo>`, `--app <slug>`, `--writer
app:<slug>|pipeline:<source>` (repeatable), `--crews`, `--phase <id>` (repeatable).
`run` also takes `--owner`, `--dry-run` and `--yes`. The phases are `repo`, `org`,
`billing`, `oltp`, `git-link`, `workspace`, `airhouse`, `app`, `secrets` and — with
`--crews` — `frontline`.

**`run` is safe to re-run**, which is the whole point: a half-finished standup is the
common case. It reads every phase before it writes, and writes only what is missing —
exactly two things, the organization and the workspace's Airhouse tenant — then prints
a checklist for the rest. It never buys the OLTP store (a billable project at a paid
provider), never provisions a subscription, never sets a secret's value and never
enrols a worker.

**It works one surface at a time.** The admin surface is refused while an
`oxyc assume` session is live, and the import that gives a workspace its git remote is
org-scoped — so a standup crosses between staff and tenant credentials twice. `plan`
prints the stage boundaries; `run` refuses before writing anything rather than
half-writing.

`verify` distinguishes **`unknown` from `no`**: a phase it could not read — an expired
token, or an assume session closing the admin surface — is not a phase that has not
happened, and only `no` fails. Exit `9` means a phase has not landed, `8` that a live
assume session blocked the attempt. `--json` gives `{id, landed, detail, next}` per
phase, which is the form to branch on.

## An agent's own credential

If you are an agent, run on your own token — never on the person's
`oxyc login`. Mint the one that fits the task; your operator approves it once
in the browser, and it is printed once and stored nowhere.

    eval "$(oxyc tokens create --sandbox-agent --app <org>/<app> --env <deployment>)"   # building a custom app in a sandbox
    eval "$(oxyc tokens create --agent --env <deployment>)"                             # everything else

- **Sandbox agent token** (`oxy_sbx_…`): the sandboxes of the apps it names,
  and nothing else on the deployment.
- **Agent token** (`oxy_pat_…`): everything your operator can reach, for hours
  (`--hours`, default 8). Add `--standing` only when the task needs their staff
  or partner access: they decide on the page, where it starts off, and a token
  that comes back without it is still a success.
- **After a mint, pass `--token-env OXY_TOKEN` to every command.** A named
  token variable is the only source, so a command that lost the variable (a new
  shell, a subprocess started without it) exits `4` instead of silently running
  on the person's cached login.
- `oxyc whoami --token-env OXY_TOKEN` says what you hold and when it ends.
  `oxyc tokens revoke --current --token-env OXY_TOKEN` ends it when the task is
  done.
- **Exit `4` on your own token means it expired or was revoked. Stop and
  report.** Do not run `oxyc login`, and do not look for another credential.

## Custom apps: what is live, healthy, used

Read-only except `domains` (below) — every other request is a GET. `<app>` is `<org-slug>/<app-slug>` or an
app UUID; each command takes `--json`.

    oxyc apps list [--org <slug>] [--published|--draft] [--builds]   # every app you can see
    oxyc apps show <app>           # live build, draft build, health, availability, 7-day usage
    oxyc apps builds <app>         # build history; which build is live, which is the draft
    oxyc apps health [<app>]       # fleet table (--needs-attention), or one app's checks and errors
    oxyc apps usage <app>          # views, visitors, tracked events over 7 days
    oxyc apps drift [<app>]        # commits in a LOCAL checkout after the live build's commit
    oxyc apps domains <app>        # custom domains: status, and the DNS records still to create

`oxyc apps domains add|verify|remove <app> <domain>` is the one part of `apps`
that writes: it serves an app on a domain the customer owns (`app.acme.com`).
`add` prints the CNAME and TXT records to create; `verify` re-checks DNS and
exits `1` while the domain is still `pending` (the checker's reason is printed)
— retry it after the records propagate, do not treat it as a hard failure.

- Use these rather than `oxyc api api/customer-apps…` by hand: they walk the
  paged listing to its end and resolve `<org>/<app>` to the id the routes take.
- **A failed request never prints as an empty result.** The part that was not
  read says `NOT READ` and the exit code is non-zero. A failing health check or
  a drifted app is a report and exits `0` — read the output, not the code.
- **`drift` answers `in sync`, `N commits ahead`, or `unknown — <reason>`.**
  `unknown` means the comparison could not be made (commit not recorded,
  repository not checked out, commit not fetched, no matching `oxy-app.json`,
  uncommitted changes) and is NOT evidence of no drift. It never fetches: run
  `git fetch` in the checkout first if you want the remote's state.

## Branch on the exit code, not the text

| | |
| --- | --- |
| `0` | fine |
| `2` | you called it wrong — fix the command, do not retry |
| `4` | not authenticated. A person: `oxyc login --env <env>`. An agent on its own token: the token ended — stop and report, never log in |
| `5` | 404 — check the path with `oxyc routes`. In an **admin** surface a 404 can be a scope boundary, not a missing row. |
| `6` | the request was malformed — check `oxyc schema` |
| `7` | 5xx / timeout / network — **retryable** |
| `8` | refused: the operation would have destroyed something |

## Traps specific to this API

- **`200` with a body of `null` can mean an expired session**, not "no such
  thing" — `/api/user` does exactly that. `oxyc` warns on stderr when it sees
  one; `oxyc whoami` tells the two apart.
- **`oxyc schema` covers the data plane, not everything.** The document is
  curated for exactly the endpoints you need to build a body for — SQL, semantic
  query, and the lookups that resolve ids. A blank schema means *undocumented*,
  not nonexistent: `oxyc routes <path>` confirms the endpoint is real and shows
  what the handler says it does.
- **`/sql/query` does not return an object by default.** It returns arrays of
  strings, **header row first** — `[["id","name"],["1","ada"]]`. `--md` renders
  that as a table; `--jq '.[1:]'` skips the header. Only `result_format:
  "parquet"` returns an object, and only that one carries `truncated`.
- **A listed route can still 404** if it is `ide-only` or `worker-only`; those
  are hidden by default and shown by `oxyc routes --all`.
- **Pick the environment deliberately.** `--env local|dev|staging|production`
  (default production), or paste a URL: `--env https://your-org.oxygen-hq.com`
  targets that deployment *and* sets `{org}`.
- **Staff hitting a tenant surface need an assume-role session.** A 403 there
  usually means no active session, not a mis-modeled role — check with
  `oxyc assume status`, which answers "none" without failing.

```bash
oxyc assume start --org <slug|uuid|url> -r "why"   # 60 min, not renewable
oxyc assume status                                 # what is live, minutes left
oxyc assume end                                    # or --all
oxyc login --login-env dev,staging                 # log into several at once
```

**No browser on this machine** (a Claude Code remote session, SSH, a
Codespace): `oxyc login` notices and prints a URL and a code to open on any
device, like `gh auth login`. An agent asked to log a person in there cannot
show a URL from a command that is still waiting, so split it:
`oxyc login --env <env> --no-wait` prints the URL on stdout and exits — hand
it to the person — and once they say it is approved, `oxyc login --env <env>`
finishes. This is the person's login, run because they asked; it is still
never your own credential (see "An agent's own credential").

**In CI** nobody can approve, so `oxyc login` and `tokens create --agent` exit
`4` at once. Use `OXY_TOKEN` from a secret, or `--service-account` under GitHub
Actions OIDC. `-q` works there too: oxyc embeds jq when the runner has none.

The session hangs off your **account**, not this terminal — your browser is in
there too, and `end` gets you out of both.

## Do not

- Do not `curl` the API by hand — you will get the credential wrong for
  `/external/api/**`, which takes `X-API-Key` rather than a bearer.
- Do not run a mutating request (`-X POST/PATCH/DELETE`) against **production**
  on your own initiative. Read freely; ask before you write.
- Do not paste a token into a command line or a file. `oxyc` reads it from the
  login cache; `oxyc token` exists if something really needs it.

