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

# CLI

> Terminal REPL for direct agent interaction

The ouroborai CLI provides both single-command execution and an interactive
REPL mode for conversing with the agent directly from your terminal. It
communicates with the same Hono API server used by all other clients.

## Commands

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
arb <command> [options]
```

| Command              | Description                              |
| -------------------- | ---------------------------------------- |
| `health`             | Check API server status                  |
| `trade <prompt>`     | Execute a spot swap via natural language |
| `perp <prompt>`      | Execute a perpetual trade                |
| `portfolio`          | Show portfolio balances and positions    |
| `timeboost [prompt]` | Query TimeBoost express lane             |
| `chat`               | Start the interactive REPL               |

### Examples

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
arb health
arb trade "swap 100 USDC for ETH"
arb perp "open 2x long ETH with 500 USDC"
arb portfolio
arb timeboost "express lane status"
arb chat
```

## Interactive REPL

The `chat` command starts a persistent REPL session with multi-turn thread
context. Each prompt in the session is sent with the same `threadId`, allowing
the agent to reference previous messages:

```
ouroborai interactive mode
Type your message. Ctrl+C to exit.

arb> swap 100 USDC for ETH
Swapped 100 USDC for 0.0312 ETH via Uniswap V3 (500bps pool).

arb> now supply half of that ETH to Aave
Supplied 0.0156 ETH to Aave V3. Health factor: 2.41.

arb> exit
Goodbye.
```

<Info>
  Thread context is maintained for the duration of the REPL session. Exiting
  with `exit`, `quit`, or `Ctrl+C` ends the session and discards the thread
  reference.
</Info>

## Authentication

The CLI supports API key authentication via a flag or environment variable:

| Method      | Usage                                    |
| ----------- | ---------------------------------------- |
| Flag        | `arb --api-key <key> trade "swap ETH"`   |
| Environment | `ARB_API_KEY=<key> arb trade "swap ETH"` |

The API key is sent as a `Bearer` token in the `Authorization` header.

## Global Flags

| Flag              | Description                                |
| ----------------- | ------------------------------------------ |
| `--api-url <url>` | Override the API server URL                |
| `--api-key <key>` | Set the API key for authenticated requests |

Global flags can appear before the command and are parsed before dispatch.

## Environment Variables

| Variable      | Default                 | Description      |
| ------------- | ----------------------- | ---------------- |
| `ARB_API_URL` | `http://localhost:3000` | API server URL   |
| `ARB_API_KEY` | (empty)                 | API key for auth |

Flags take precedence over environment variables.

## API Communication

All commands follow the same request lifecycle:

<AccordionGroup>
  <Accordion title="1. Submit prompt">
    `POST /agent/prompt` with a JSON body containing the prompt text and an
    optional `threadId` (REPL mode only). Returns a `jobId`.
  </Accordion>

  <Accordion title="2. Poll for result">
    `GET /agent/job/{jobId}` polled every 2 seconds until the job reaches a
    terminal state (`complete`, `failed`, or `cancelled`). Timeout is 120
    seconds.
  </Accordion>

  <Accordion title="3. Display result">
    Completed jobs display the `result.text` field. Failed jobs display the
    error message. In REPL mode, a spinner animates during both the submission
    and polling phases.
  </Accordion>
</AccordionGroup>

## Setup

<AccordionGroup>
  <Accordion title="Install and run">
    The CLI entry point is a Bun script:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    bun run apps/cli/src/index.ts health
    ```

    To use it as a global `arb` command, link the binary:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    bun link
    ```
  </Accordion>

  <Accordion title="Point to a remote API">
    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    arb --api-url https://api.ouroborai.com --api-key sk-xxx chat
    ```

    Or set environment variables:

    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    export ARB_API_URL=https://api.ouroborai.com
    export ARB_API_KEY=sk-xxx
    arb chat
    ```
  </Accordion>
</AccordionGroup>

## Terminal Output

The CLI uses ANSI color codes for readable terminal output:

| Element          | Color       |
| ---------------- | ----------- |
| Brand text       | Cyan + bold |
| Success messages | Green       |
| Error messages   | Red         |
| Dim / help text  | Dim gray    |

A box-drawing utility formats structured output with borders and headers. The
REPL spinner cycles through braille animation frames during async operations.

<Tip>
  The `chat` command is the most powerful mode -- it preserves conversation
  context across turns, so you can issue follow-up instructions like "close
  half that position" without repeating context.
</Tip>