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.
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:
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:
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.
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 nojqon PATH (oxyc embeds jq), so use it in CI and cloud VMs too.--mdturns 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 5mwhen you are walking the same endpoints repeatedly.--paginatemerges 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--standingonly 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_TOKENto 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) exits4instead of silently running on the person's cached login. oxyc whoami --token-env OXY_TOKENsays what you hold and when it ends.oxyc tokens revoke --current --token-env OXY_TOKENends it when the task is done.- Exit
4on your own token means it expired or was revoked. Stop and report. Do not runoxyc 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 READand the exit code is non-zero. A failing health check or a drifted app is a report and exits0— read the output, not the code. driftanswersin sync,N commits ahead, orunknown — <reason>.unknownmeans the comparison could not be made (commit not recorded, repository not checked out, commit not fetched, no matchingoxy-app.json, uncommitted changes) and is NOT evidence of no drift. It never fetches: rungit fetchin 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
200with a body ofnullcan mean an expired session, not "no such thing" —/api/userdoes exactly that.oxycwarns on stderr when it sees one;oxyc whoamitells the two apart.oxyc schemacovers 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/querydoes not return an object by default. It returns arrays of strings, header row first —[["id","name"],["1","ada"]].--mdrenders that as a table;--jq '.[1:]'skips the header. Onlyresult_format: "parquet"returns an object, and only that one carriestruncated.- A listed route can still 404 if it is
ide-onlyorworker-only; those are hidden by default and shown byoxyc routes --all. - Pick the environment deliberately.
--env local|dev|staging|production(default production), or paste a URL:--env https://your-org.oxygen-hq.comtargets 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.
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
curlthe API by hand — you will get the credential wrong for/external/api/**, which takesX-API-Keyrather 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.
oxycreads it from the login cache;oxyc tokenexists if something really needs it.