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.

# Not published to npm yet, so `npx @oxy-hq/cli` 404s. From a checkout:
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.
• --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>.