CLI - Octav Developer Docs

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.

Quick Install — One command to get started:

curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh

Why Use the CLI?

AI Agent Tool-Use

Structured JSON output that AI agents can parse and act on — no SDK or HTTP client needed

Terminal Workflows

Pipe portfolio data into jq, scripts, cron jobs, or monitoring systems

Fast & Lightweight

Written in Rust — single binary, no runtime dependencies, instant startup

Interactive Dashboard

Explore holdings, protocols, chains, and transactions in a terminal UI with octav dashboard

Installation

Shell Script (Recommended)
Cargo
From Source

Works on macOS and Linux:

curl -sSf https://raw.githubusercontent.com/Octav-Labs/octav-cli/main/install.sh | sh

If you have Rust installed:

cargo install octav

Clone and build:

git clone https://github.com/Octav-Labs/octav-cli.git
cd octav-cli
cargo build --release
cp target/release/octav /usr/local/bin/

Updating

octav --version          # show the installed version
octav update --check     # check for a newer release
octav update             # install the latest release

octav update replaces the binary installed by the shell script. If you installed with Cargo, run cargo install octav instead; for source builds, git pull and rebuild. octav update tells you which applies. Versions before 0.3.0 don’t have octav update, so reinstall them with the shell script or Cargo. Before installing, octav update checks the download against the SHA-256 checksum published with the release, and stops without changing anything if it doesn’t match.

In an interactive terminal, the CLI checks for a new release at most once a day and prints a notice to stderr if one is available. The check never runs in scripts, CI, or other non-interactive use, and never changes command output. Set OCTAV_NO_UPDATE_CHECK=1 to turn it off.

Authentication

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

# 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:

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

For AI agent workflows, set the OCTAV_API_KEY environment variable so the agent doesn’t need to manage config files.

Dashboard

An interactive terminal UI for exploring a portfolio: holdings with token icons, protocol breakdown, chain distribution, and transactions.

octav dashboard --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Key	Action
`Tab` / `1-4`	Switch screens (Overview, Holdings, Protocols, Transactions)
`j` / `k`	Scroll down / up
`g` / `G`	Jump to top / bottom
`Enter`	Drill into protocol details
`Esc`	Go back
`r`	Refresh data
`q`	Quit

Token images are cached locally in ~/.octav/cache/images/.

Commands

Portfolio

octav portfolio get

Full portfolio including DeFi positions across all chains.

octav portfolio get --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Flag	Description
`--explorer-urls`	Include blockchain explorer URLs for assets and transactions
`--no-wait-for-sync`	Return cached data immediately instead of waiting for a fresh sync

Cost: 1 credit per address

octav portfolio wallet

Wallet token balances only (excludes DeFi protocol positions).

octav portfolio wallet --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit per address

octav portfolio nav

Net asset value in a specified currency.

octav portfolio nav --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --currency EUR

Supported fiat currencies: USD (default), EUR, CAD, AED, CHF, SGD. Crypto: ETH, SOL, cbBTC, EURC, BNB.Cost: 1 credit per address

octav portfolio token-overview

Aggregated token distribution across all chains for a specific date.

octav portfolio token-overview \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --date 2024-06-01

Cost: 1 credit per address

octav portfolio at-block

A single EVM address’s portfolio valued at a specific block on ethereum, linea, or monad.

octav portfolio at-block \
  --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --chain ethereum \
  --block 20000000

Cost: 1 credit, plus the Portfolio at Block add-on. See Portfolio at Block.

Transactions

octav transactions get

Query transaction history with filtering and pagination.

octav transactions get \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --chain ethereum,arbitrum \
  --type SWAP \
  --hide-spam \
  --start-date 2024-01-01 \
  --end-date 2024-06-30 \
  --limit 100

Flag	Description	Default
`--chain`	Filter by chain keys, comma-separated (see `octav chains list`)	all
`--type`	Filter by transaction types, comma-separated (e.g. `SWAP,DEPOSIT`). See Transaction Types.	all
`--protocol`	Filter by protocol keys, comma-separated (see `octav chains protocols`)	all
`--interacting-address`	Filter by counterparty addresses, comma-separated	all
`--search`	Full-text search over token symbols, names, and addresses	—
`--token-id`	Filter by NFT token ID	—
`--start-date`	Start date (YYYY-MM-DD)	—
`--end-date`	End date (YYYY-MM-DD)	—
`--sort`	`asc` or `desc` by timestamp	`desc`
`--hide-spam`	Exclude spam transactions	off
`--hide-dust`	Exclude dust transactions	off
`--offset`	Pagination offset	`0`
`--limit`	Results per page (max 250)	`50`

Cost: 1 credit per address

octav transactions sync

Trigger manual transaction synchronization.

octav transactions sync --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit per address

Historical

octav historical get

Portfolio snapshot for a specific date.

octav historical get \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --date 2024-01-01

Cost: 1 credit per address

Subscribe to automatic daily portfolio snapshots.

octav historical subscribe-snapshot \
  --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 \
  --description "Main wallet daily snapshot"

Cost: 1,200 credits per address per year. See Subscribe Snapshot.

Metadata & Specialized

octav status

Check sync status for addresses.

octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: Free

octav credits

Check API credit balance.

octav credits

Cost: Free

octav chains list

List supported chains, with the keys that --chain flags take.

octav chains list

Cost: Free

octav chains protocols

List the protocols on a chain, with the keys that --protocol takes. Paginated.

octav chains protocols --chain ethereum --page 1 --limit 20

Flag	Description	Default
`--chain`	Chain key (required)	—
`--page`	Page number	`1`
`--limit`	Protocols per page (1–100)	`20`

Cost: Free

octav contract-protocol

Find which DeFi protocol a contract address belongs to. Omit --chain to search all chains.

octav contract-protocol --contract 0x1111111254eeb25477b68fb85ed929f73a960582 --chain arbitrum

Cost: 5 credits, refunded if no protocol is found

octav airdrop

Check Solana airdrop eligibility.

octav airdrop --address 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

Cost: 1 credit

octav polymarket

Get Polymarket prediction market positions.

octav polymarket --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68

Cost: 1 credit

octav approvals

ERC-20 token approvals an EVM wallet has granted on one chain. Paginated with --limit (1–100, default 25) and --cursor.

octav approvals --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --chain ethereum

Supported chains: arbitrum, avalanche, base, binance, ethereum, fantom, gnosis, linea, optimism, polygon.Cost: 1 credit

Address Book & Bundles

Address book and bundle commands are the only ones that change data on your Octav account. Every other command is read-only. Each call costs 1 credit.

Command	Effect	Needs `--yes`
`addressbook add`	Adds addresses	No
`addressbook rename`	Overwrites a label	Yes
`addressbook remove`	Deletes an address	Yes
`bundles create`	Creates a bundle	No
`bundles add-address`	Adds an address to a bundle	No
`bundles rename`	Overwrites a bundle name	Yes
`bundles remove-address`	Removes an address from a bundle	Yes
`bundles delete`	Deletes a bundle	Yes

Commands that delete or overwrite data refuse to run without --yes. They exit with an error of type confirmation_required without sending any request:

{
  "error": {
    "type": "confirmation_required",
    "message": "This permanently deletes bundle abc123 from your Octav account (its addresses stay in the address book). Re-run with --yes to confirm."
  }
}

AI agents should treat confirmation_required as a stop: check with the user before re-running with --yes.

octav addressbook

Manage the addresses saved to your account, the same list you see in Octav Pro. Addresses already in the book keep their existing label when added again. See Address Book.

octav addressbook list
octav addressbook add --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --label "Main wallet"
octav addressbook add --addresses 0xABC...123,0xDEF...456     # up to 100, no labels
octav addressbook rename --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --label "Treasury" --yes
octav addressbook remove --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --yes

octav bundles

Named groups of address book entries. Addresses must already be in the address book. By default an account can have 5 bundles of up to 10 addresses each. See Bundles.

octav bundles list
octav bundles get --id <BUNDLE_ID>
octav bundles create --name "Treasury" --addresses 0xABC...123,0xDEF...456
octav bundles rename --id <BUNDLE_ID> --name "Core Treasury" --yes
octav bundles add-address --id <BUNDLE_ID> --address 0xABC...123
octav bundles remove-address --id <BUNDLE_ID> --address 0xABC...123 --yes
octav bundles delete --id <BUNDLE_ID> --yes      # addresses stay in the address book

Virtual Users

Virtual users are balance-tracking or CEX-linked accounts managed in Octav Pro, addressed as virtual:<id>. They require Pro. See Virtual Users.

octav virtual-users list

List the virtual users on your account.

octav virtual-users list

Cost: 1 credit

octav virtual-users portfolio

Portfolios for virtual users, using virtual:<id> addresses from virtual-users list. Add --aggregated for one combined portfolio. Accepts the same --explorer-urls and --no-wait-for-sync flags as portfolio get.

octav virtual-users portfolio --addresses virtual:abc123,virtual:def456 --aggregated

Cost: 1 credit per address

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

"Check the portfolio value for 0xABC... using the octav CLI,
then analyze the DeFi positions and suggest rebalancing opportunities."

The agent runs:

octav portfolio get --addresses 0xABC... --raw

And receives structured JSON it can reason over.

Example: Autonomous Monitoring Script

#!/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:

# Pretty-printed (default)
octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68
# => [
# =>   {
# =>     "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd68",
# =>     "syncInProgress": false,
# =>     ...
# =>   }
# => ]

# Compact JSON (ideal for piping / agent parsing)
octav status --addresses 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68 --raw
# => [{"address":"0x742d35cc6634c0532925a3b844bc9e7595f2bd68","syncInProgress":false,...}]

octav credits prints a bare number (e.g. 4872), so use it directly rather than with jq '.credits'. The --raw flag also disables field stripping, returning the full API response.

Multiple Addresses

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

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:

{
  "error": {
    "type": "auth",
    "message": "Invalid API key",
    "status": 401
  }
}

Error	Cause	Solution
Invalid address format	Address doesn’t match the format the command accepts	Use `0x...` (40 hex chars) for EVM or base58 for Solana. Address book and bundle commands also accept Tron.
`confirmation_required`	A command that deletes or overwrites data was run without `--yes`	Check with the user, then re-run with `--yes`
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

Resources

GitHub

Source code and issues

API Docs

Full REST API reference

Pricing

Credit packages and costs

​Why Use the CLI?

AI Agent Tool-Use

Terminal Workflows

Fast & Lightweight

Interactive Dashboard

​Installation

​Updating

​Authentication

​Dashboard

​Commands

​Portfolio

​Transactions

​Historical

​Metadata & Specialized

​Address Book & Bundles

​Virtual Users

​Using with AI Agents

​Example: Claude Code / Cursor Agent

​Example: Autonomous Monitoring Script

​Output Format

​Multiple Addresses

​Error Handling

​Resources

GitHub

API Docs

Pricing

Why Use the CLI?

Installation

Updating

Authentication

Dashboard

Commands

Portfolio

Transactions

Historical

Metadata & Specialized

Address Book & Bundles

Virtual Users

Using with AI Agents

Example: Claude Code / Cursor Agent

Example: Autonomous Monitoring Script

Output Format

Multiple Addresses

Error Handling

Resources