> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install @0xarchive/cli and run shell-native market-data commands with JSON output.

Use the CLI when the job belongs in a terminal: local checks, cron, CI, notebooks, incident terminals, and coding-agent shells with command access.

The package is `@0xarchive/cli`. The binary is `oxa`. The CLI uses `OXA_API_KEY`.

Use this page as the shell contract: pick a venue scope, pass an explicit symbol and window, request JSON for machine consumers, and branch on exit codes instead of scraping terminal text.

<Steps>
  <Step title="Run one auth check">
    ```bash theme={"theme":"github-dark"}
    npx @0xarchive/cli auth test
    ```
  </Step>

  <Step title="Install it for repeated use">
    ```bash theme={"theme":"github-dark"}
    npm install -g @0xarchive/cli
    ```
  </Step>

  <Step title="Set the CLI key">
    ```bash theme={"theme":"github-dark"}
    export OXA_API_KEY="0xa_your_api_key"
    ```
  </Step>

  <Step title="Pull one market payload">
    ```bash theme={"theme":"github-dark"}
    oxa orderbook get --exchange hyperliquid --symbol BTC --format json
    ```
  </Step>
</Steps>

## Preflight Packet

Before wiring the CLI into a script, make these inputs explicit.

| Input       | CLI shape                                                                                               | Notes                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| API key     | `OXA_API_KEY`                                                                                           | Store it in the shell, CI secret store, or ignored local environment file                               |
| Venue scope | `--exchange hyperliquid`, `--exchange lighter`, `--exchange hip3`, `--exchange hip4`, or `oxa spot ...` | HIP-3 and HIP-4 are Hyperliquid-scoped market families, but the CLI exposes convenience scopes for them |
| Symbol      | `BTC`, `ETH`, `km:US500`, `0`, `HYPE-USDC`                                                              | Keep HIP-3 prefixes case-sensitive; use bare numeric HIP-4 outcome IDs where possible                   |
| Window      | `--start`, `--end`, `--interval`, `--limit`, `--cursor`                                                 | Start with a small bounded window, then paginate or widen after the first response looks right          |
| Output      | `--format json`                                                                                         | JSON is the safest default for agents, CI, notebooks, and downstream scripts                            |

## Command Model

<CodeGroup>
  ```bash Hyperliquid order book theme={"theme":"github-dark"}
  oxa orderbook get --exchange hyperliquid --symbol BTC --format json
  ```

  ```bash Lighter trades theme={"theme":"github-dark"}
  oxa trades fetch --exchange lighter --symbol BTC --limit 50 --format json
  ```

  ```bash HIP-3 candles theme={"theme":"github-dark"}
  oxa candles --exchange hip3 --symbol km:US500 \
    --start 2026-03-01T00:00:00Z \
    --end 2026-03-02T00:00:00Z \
    --interval 1h \
    --format json
  ```

  ```bash HIP-4 outcomes theme={"theme":"github-dark"}
  oxa hip4 outcomes list --settled false --format json
  ```

  ```bash Spot pairs theme={"theme":"github-dark"}
  oxa spot pairs --format json
  ```
</CodeGroup>

## Where The CLI Fits

| Job               | Use the CLI when                                                         | Use something else when                                    |
| ----------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Shell automation  | The output should go to `jq`, a file, cron, CI, or a notebook setup step | The integration lives inside long-running application code |
| Coding-agent work | The agent can run terminal commands and inspect JSON                     | The host supports MCP and typed tools are a better fit     |
| Data checks       | You need a bounded route, freshness check, or auth probe fast            | You need full route/schema generation before writing code  |
| Incident work     | You need stable stdout, stderr, and exit codes                           | You need a dashboard or browser-first debugging surface    |

## Command Inventory

| Command                                       | Coverage                                                                            |
| --------------------------------------------- | ----------------------------------------------------------------------------------- |
| `oxa auth test`                               | Verify the key and optionally test a venue/symbol pair                              |
| `oxa orderbook get`                           | Current L2 order-book snapshot                                                      |
| `oxa orderbook history`                       | Historical L2 snapshots                                                             |
| `oxa trades fetch`                            | Trade history with cursor pagination                                                |
| `oxa candles`                                 | OHLCV candles                                                                       |
| `oxa funding current` / `oxa funding history` | Current and historical funding                                                      |
| `oxa oi current` / `oxa oi history`           | Current and historical open interest                                                |
| `oxa instruments`                             | Venue instrument list                                                               |
| `oxa liquidations`                            | Liquidation history where the venue family supports it                              |
| `oxa summary`                                 | Multi-signal market snapshot                                                        |
| `oxa prices`                                  | Price history                                                                       |
| `oxa freshness`                               | Per-symbol freshness                                                                |
| `oxa orders history` / `flow` / `tpsl`        | Order lifecycle and flow routes where the plan allows them                          |
| `oxa l4 get` / `diffs` / `history`            | L4 reconstruction and checkpoint routes                                             |
| `oxa l3 get` / `history`                      | Lighter L3 depth                                                                    |
| `oxa hip4 ...`                                | Outcome-market discovery, books, trades, candles, OI, prices, summaries, and orders |
| `oxa spot ...`                                | Hyperliquid Spot pairs, books, trades, L4, orders, TWAP, and freshness              |
| `oxa stream ...`                              | Stream commands for supported realtime jobs                                         |

## Automation Contract

| Stream        | Behavior                                                   |
| ------------- | ---------------------------------------------------------- |
| stdout        | JSON or pretty output from successful commands             |
| stderr        | Validation, auth, network, rate-limit, and internal errors |
| exit code `0` | Command completed                                          |
| exit code `2` | Validation or argument error                               |
| exit code `3` | Authentication error                                       |
| exit code `4` | Network, upstream API, or rate-limit error                 |
| exit code `5` | Internal CLI error                                         |

```bash theme={"theme":"github-dark"}
oxa auth test 2>/dev/null && echo "ready"

oxa summary --exchange hyperliquid --symbol BTC --format json \
  | jq '{symbol, markPrice, fundingRate, openInterest}'

oxa freshness --exchange hyperliquid --symbol BTC --format json \
  | jq '.data'
```

## Pagination And Failure Handling

Historical commands can return a `nextCursor`. Pass that value back with `--cursor` for the next page, and keep the original venue, symbol, window, and format arguments unchanged unless you choose a broader request.

Treat stdout as the data channel and stderr as the control channel. For unattended jobs, parse JSON only from stdout, preserve any returned `request_id` or cursor in logs, and branch on the exit code before retrying. Validation and auth failures should stop the job; network, upstream API, and rate-limit failures can use bounded retries.

## Choose Data Catalog Instead

Use [Data Catalog](/data) when the job is a large historical export, full backfill, Parquet workflow, or warehouse load. The CLI is strongest for point queries, moderate pulls, freshness checks, scripted probes, and terminal-native incident work.

## Why 0xArchive Fits

The CLI exposes the same market-data jobs as the API in a shell shape: venue selection, symbol selection, bounded history, freshness checks, JSON output, and deterministic command failure.

## Production Notes

Use the CLI when a workflow wants a command boundary: CI checks, cron jobs, notebook setup, incident response, local exports, or coding-agent terminal work. Keep command arguments explicit, prefer `--format json` for machine consumers, and send JSON through `jq` or a script instead of scraping human text.

Do not use the CLI as a hidden dependency inside a long-running application server if an SDK or REST client would be easier to observe and test. The CLI is strongest when process exit codes, stdout, stderr, and shell composition are the product requirement.

## Next Step

Use [Choose An Interface](/tooling) to compare CLI with MCP, Skill, SDKs, REST, and OpenAPI. Use [OpenAPI](/openapi) when you need generated clients or route/schema contract.