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

# CLI

> Query portfolio data, transactions, net worth, and historical snapshots across 20+ blockchains from your terminal or AI agent workflows

The official Octav CLI lets you interact with the Octav API directly from your terminal. Built in Rust for speed, it outputs structured JSON — making it ideal for shell scripts, CI pipelines, and AI agent tool-use.

<Info>
  **Quick Install** — One command to get started:

  ```bash theme={null}
  curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh
  ```
</Info>

***

## Why Use the CLI?

<CardGroup cols={2}>
  <Card title="AI Agent Tool-Use" icon="robot">
    Structured JSON output that AI agents can parse and act on — no SDK or HTTP client needed
  </Card>

  <Card title="Terminal Workflows" icon="terminal">
    Pipe portfolio data into jq, scripts, cron jobs, or monitoring systems
  </Card>

  <Card title="Fast & Lightweight" icon="bolt">
    Written in Rust — single binary, no runtime dependencies, instant startup
  </Card>

  <Card title="x402 Agent Payments" icon="credit-card">
    Built-in support for the x402 payment protocol — AI agents can pay per request without API keys
  </Card>
</CardGroup>

***

## Installation

<Tabs>
  <Tab title="Shell Script (Recommended)" icon="bolt">
    Works on macOS and Linux:

    ```bash theme={null}
    curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh
    ```
  </Tab>

  <Tab title="Cargo" icon="rust">
    If you have Rust installed:

    ```bash theme={null}
    cargo install octav
    ```
  </Tab>

  <Tab title="From Source" icon="code">
    Clone and build:

    ```bash theme={null}
    git clone https://github.com/Octav-Labs/octav-cli.git
    cd octav-cli
    cargo build --release
    cp target/release/octav /usr/local/bin/
    ```
  </Tab>
</Tabs>

***

## Authentication

Store your API key once and it's used automatically for all commands.

```bash theme={null}
# Store your API key (get one at https://data.octav.fi)
octav auth set-key YOUR_API_KEY

# Verify it's set
octav auth show
```

The API key is resolved in priority order:

1. `--api-key` flag (highest precedence)
2. `OCTAV_API_KEY` environment variable
3. `~/.octav/config.json` config file

<Tip>
  For AI agent workflows, set the `OCTAV_API_KEY` environment variable so the agent doesn't need to manage config files.
</Tip>

***

## Commands

### Portfolio

<AccordionGroup>
  <Accordion title="octav portfolio get" icon="wallet">
    **Full portfolio including DeFi positions across all chains.**

    ```bash theme={null}
    octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```

    **Cost:** 1 credit per address
  </Accordion>

  <Accordion title="octav portfolio wallet" icon="coins">
    **Wallet token balances only (excludes DeFi protocol positions).**

    ```bash theme={null}
    octav portfolio wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```

    **Cost:** 1 credit per address
  </Accordion>

  <Accordion title="octav portfolio nav" icon="calculator">
    **Net asset value in a specified currency.**

    ```bash theme={null}
    octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --currency EUR
    ```

    Supported currencies: `USD` (default), `EUR`, `GBP`, `JPY`, `CNY`.

    **Cost:** 1 credit per address
  </Accordion>

  <Accordion title="octav portfolio token-overview" icon="chart-pie">
    **Aggregated token distribution across all chains for a specific date.**

    ```bash theme={null}
    octav portfolio token-overview \
      --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
      --date 2024-06-01
    ```

    **Cost:** 1 credit per address
  </Accordion>
</AccordionGroup>

### Transactions

<AccordionGroup>
  <Accordion title="octav transactions get" icon="receipt">
    **Query transaction history with filtering and pagination.**

    ```bash theme={null}
    octav transactions get \
      --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
      --chain ethereum \
      --type swap \
      --start-date 2024-01-01 \
      --end-date 2024-06-30 \
      --limit 100
    ```

    | Flag           | Description                | Default |
    | -------------- | -------------------------- | ------- |
    | `--chain`      | Filter by chain            | all     |
    | `--type`       | Filter by transaction type | all     |
    | `--start-date` | Start date (YYYY-MM-DD)    | —       |
    | `--end-date`   | End date (YYYY-MM-DD)      | —       |
    | `--offset`     | Pagination offset          | `0`     |
    | `--limit`      | Results per page (max 250) | `50`    |

    **Cost:** 1 credit per address
  </Accordion>

  <Accordion title="octav transactions sync" icon="arrows-rotate">
    **Trigger manual transaction synchronization.**

    ```bash theme={null}
    octav transactions sync --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```

    **Cost:** 1 credit per address
  </Accordion>
</AccordionGroup>

### Historical

<AccordionGroup>
  <Accordion title="octav historical get" icon="clock">
    **Portfolio snapshot for a specific date.**

    ```bash theme={null}
    octav historical get \
      --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
      --date 2024-01-01
    ```

    **Cost:** 1 credit per address
  </Accordion>

  <Accordion title="octav historical subscribe-snapshot" icon="bell">
    **Subscribe to automatic daily portfolio snapshots.**

    ```bash theme={null}
    octav historical subscribe-snapshot \
      --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
      --description "Main wallet daily snapshot"
    ```

    **Cost:** 1 credit per address
  </Accordion>
</AccordionGroup>

### Metadata & Specialized

<AccordionGroup>
  <Accordion title="octav status" icon="circle-check">
    **Check sync status for addresses.**

    ```bash theme={null}
    octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```

    **Cost:** Free
  </Accordion>

  <Accordion title="octav credits" icon="tag">
    **Check API credit balance.**

    ```bash theme={null}
    octav credits
    ```

    **Cost:** Free
  </Accordion>

  <Accordion title="octav airdrop" icon="gift">
    **Check Solana airdrop eligibility.**

    ```bash theme={null}
    octav airdrop --address 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
    ```

    **Cost:** 1 credit
  </Accordion>

  <Accordion title="octav polymarket" icon="chart-line">
    **Get Polymarket prediction market positions.**

    ```bash theme={null}
    octav polymarket --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```

    **Cost:** 1 credit
  </Accordion>
</AccordionGroup>

### Agent Commands (x402)

For AI agents that pay per request using the [x402 payment protocol](https://www.x402.org/) — no API key required.

<AccordionGroup>
  <Accordion title="octav agent wallet" icon="robot">
    **Wallet holdings via x402 payment.**

    ```bash theme={null}
    octav agent wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```
  </Accordion>

  <Accordion title="octav agent portfolio" icon="robot">
    **Full portfolio via x402 payment.**

    ```bash theme={null}
    octav agent portfolio --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
    ```
  </Accordion>
</AccordionGroup>

***

## Using with AI Agents

The CLI outputs structured JSON, making it a natural fit for AI agent tool-use. Agents can invoke `octav` commands via shell execution and parse the JSON response directly.

### Example: Claude Code / Cursor Agent

```text theme={null}
"Check the portfolio value for 0xABC... using the octav CLI,
then analyze the DeFi positions and suggest rebalancing opportunities."
```

The agent runs:

```bash theme={null}
octav portfolio get --addresses 0xABC... --raw
```

And receives structured JSON it can reason over.

### Example: Autonomous Monitoring Script

```bash theme={null}
#!/bin/bash
# Daily portfolio snapshot with alerts

ADDR="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
NAV=$(octav portfolio nav --addresses $ADDR --raw | jq -r '.nav')

echo "Portfolio value: $NAV"

# Agent can parse this output and decide on actions
```

### Output Format

All commands return JSON. Pretty-printed by default, compact with `--raw`:

```bash theme={null}
# Pretty-printed (default)
octav credits
# => {
# =>   "credits": 42
# => }

# Compact JSON (ideal for piping / agent parsing)
octav credits --raw
# => {"credits":42}
```

The `--raw` flag also disables field stripping, returning the full API response.

***

## Multiple Addresses

Most commands accept multiple addresses as a comma-separated list:

```bash theme={null}
octav portfolio get \
  --addresses 0xABC...123,0xDEF...456,7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
```

Maximum 10 addresses per request.

***

## Error Handling

Errors are returned as JSON on stdout with a non-zero exit code:

```json theme={null}
{
  "error": {
    "type": "auth",
    "message": "Invalid API key",
    "status": 401
  }
}
```

| Error                  | Cause                                      | Solution                                                 |
| ---------------------- | ------------------------------------------ | -------------------------------------------------------- |
| Invalid address format | Address doesn't match EVM or Solana format | Use `0x...` (40 hex chars) for EVM or base58 for Solana  |
| Authentication failure | Missing or invalid API key                 | Run `octav auth set-key` or set `OCTAV_API_KEY`          |
| Insufficient credits   | Not enough credits for the request         | Purchase more at [data.octav.fi](https://data.octav.fi/) |

***

## Resources

<CardGroup cols={3}>
  <Card title="GitHub" icon="github" href="https://github.com/Octav-Labs/octav-cli">
    Source code and issues
  </Card>

  <Card title="API Docs" icon="book" href="/api/introduction">
    Full REST API reference
  </Card>

  <Card title="Pricing" icon="tag" href="/api/pricing">
    Credit packages and costs
  </Card>
</CardGroup>