CLI

What is the Compass CLI?

compass is a single binary that wraps the Compass DeFi API. Every endpoint is available as a subcommand, output can be rendered as JSON / YAML / table / TOON, and an --agent-mode flag tunes the experience for AI agents calling tools. Use it for:

Inspecting positions, balances, and vaults from the terminal
Scripting workflows in shell or CI
Giving an autonomous AI agent a typed tool surface for Compass

Using an AI coding agent?

Install the Compass agent skill and Claude Code, Cursor, or Codex maps your plain-English DeFi requests to these commands for you — no manual scripting.

Install

Homebrew
macOS / Linux
Windows
Go
Manual

brew install compasslabs/tap/compass

Update later with brew upgrade compass.

curl -fsSL https://compasslabs.ai/install.sh | bash

iwr -useb https://compasslabs.ai/install.ps1 | iex

go install github.com/CompassLabs/cli/cmd/compass@latest

Verify the install:

compass version

Authenticate

Run the interactive configure command — it stores your API key in the OS keychain (macOS Keychain, GNOME Keyring/KWallet on Linux, Windows Credential Locker):

compass configure

Or set it via environment variable for CI:

export COMPASS_API_KEY_AUTH="your_api_key_here"

Or pass it per-command:

compass --api-key-auth "your_api_key_here" earn vaults --order-by tvl_usd

Priority order: CLI flags > environment variables > saved credentials (from compass configure).

Get a free API key at compasslabs.ai/login.

Quickstart

List the top 5 vaults by TVL:

compass earn vaults \
  --order-by tvl_usd \
  --direction desc \
  --limit 5 \
  -o table \
  -q '.vaults'

Check the live state of an earn position:

compass earn positions --chain base --owner 0xYourAddress -o json

Filter with jq directly from the CLI — list only Morpho vaults by name:

compass earn vaults --order-by tvl_usd -q '.vaults[] | select(.protocol == "Morpho") | .name'

Agent mode

The CLI ships with an --agent-mode flag that:

Switches default output to TOON (a compact, token-efficient format ideal for LLM context)
Emits structured errors that agents can parse and react to

It auto-activates when invoked from a known agent environment (CLAUDE_CODE, CURSOR_AGENT, etc.) — so when an AI assistant shells out to compass …, it already gets agent-friendly output.

# Explicitly enable
compass --agent-mode earn vaults --order-by tvl_usd

# Explicitly disable (e.g. inside an agent env but you want pretty output)
compass --agent-mode=false earn vaults --order-by tvl_usd

You can also dump the full command schema in KDL for tool generation:

compass --usage

Output formats

-o pretty    # default — human-friendly, colored
-o json      # machine-readable
-o yaml      # readable + machine-parseable
-o table     # tabular, great for terminals
-o toon      # token-efficient, default in agent mode

Combine with -q '<jq expression>' to filter / reshape on the way out.

Command groups

Group	What it does
`compass auth`	Manage authentication credentials
`compass configure`	Interactive credential + preference setup
`compass earn`	Vault discovery, positions, balances, deposits, withdrawals, swaps
`compass credit`	Crypto-backed loans: balances, borrow, repay, positions
`compass gas-sponsorship`	Prepare gas-sponsored transactions
`compass tokenized-equities`	Tokenized equities operations
`compass onramp`	Fiat on-ramp — `quote` / `create` / `status`, plus `buy` (buy USDC with a card)
`compass risk-recipes`	Print risk-analysis recipes (LLTV cascade, JTD, vault correlation)
`compass perpetual-trading`	Perpetuals on global markets
`compass explore`	Interactively browse and run any command

Run compass <group> --help for the full subcommand list, or compass explore to browse interactively.

compass onramp buy is a gh auth login-style handoff: it runs quote → create, auto-opens the checkout_url in your default browser (printing the URL as a fallback), then polls compass onramp status with a spinner until the payment is delivered. In headless / CI / agent mode it skips the browser + spinner and just prints the URL + instructions to poll. See On-Ramp.

Shell completion

# Bash
source <(compass completion bash)

# Zsh
source <(compass completion zsh)

# Fish
compass completion fish | source

# PowerShell
compass completion powershell | Out-String | Invoke-Expression

Full command reference

Per-command documentation (every flag, every subcommand) lives in the CLI source tree:

Browse the full command reference

Auto-generated docs for every compass subcommand.

Coding Assistant

Want an AI assistant to write the integration for you? Point it at Compass’s LLM-optimized docs.

API Reference

The REST endpoints the CLI wraps. Useful for understanding what each subcommand does on the wire.

Get Started

Quick Guides

Agents

Products

Features

Support

What is the Compass CLI?

Using an AI coding agent?

Install

Authenticate

Quickstart

Agent mode

Output formats

Command groups

Shell completion

Full command reference

Browse the full command reference

Coding Assistant

API Reference

​What is the Compass CLI?

Using an AI coding agent?

​Install

​Authenticate

​Quickstart

​Agent mode

​Output formats

​Command groups

​Shell completion

​Full command reference

Browse the full command reference

Coding Assistant

API Reference

What is the Compass CLI?

Install

Authenticate

Quickstart

Agent mode

Output formats

Command groups

Shell completion

Full command reference