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

# CLI

> The compass CLI — a scriptable command-line interface to every Compass API endpoint, with first-class support for AI agents.

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

<Card title="Using an AI coding agent?" icon="puzzle-piece" href="/v2/Agents/Agent-Skill">
  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.
</Card>

***

## Install

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={"system"}
    brew install compasslabs/tap/compass
    ```

    Update later with `brew upgrade compass`.
  </Tab>

  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    curl -fsSL https://compasslabs.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"system"}
    iwr -useb https://compasslabs.ai/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={"system"}
    go install github.com/CompassLabs/cli/cmd/compass@latest
    ```
  </Tab>

  <Tab title="Manual">
    Download a pre-built binary for your platform from the [releases page](https://github.com/CompassLabs/cli/releases).
  </Tab>
</Tabs>

Verify the install:

```bash theme={"system"}
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):

```bash theme={"system"}
compass configure
```

Or set it via environment variable for CI:

```bash theme={"system"}
export COMPASS_API_KEY_AUTH="your_api_key_here"
```

Or pass it per-command:

```bash theme={"system"}
compass --api-key-auth "your_api_key_here" earn vaults --order-by tvl_usd
```

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

Get a free API key at [compasslabs.ai/login](https://www.compasslabs.ai/login).

***

## Quickstart

List the top 5 vaults by TVL:

```bash theme={"system"}
compass earn vaults \
  --order-by tvl_usd \
  --direction desc \
  --limit 5 \
  -o table \
  -q '.vaults'
```

Check the live state of an earn position:

```bash theme={"system"}
compass earn positions --chain base --owner 0xYourAddress -o json
```

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

```bash theme={"system"}
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.

```bash theme={"system"}
# 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:

```bash theme={"system"}
compass --usage
```

***

## Output formats

```bash theme={"system"}
-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`               | Credit lines: balances, borrow, repay, positions                   |
| `compass gas-sponsorship`      | Prepare gas-sponsored transactions                                 |
| `compass tokenized-equities`   | Tokenized equities operations                                      |
| `compass risk-recipes`         | Print risk-analysis recipes (LLTV cascade, JTD, vault correlation) |
| `compass global-markets-perps` | 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.

***

## Shell completion

```bash theme={"system"}
# 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:

<Card title="Browse the full command reference" icon="github" href="https://github.com/CompassLabs/cli/tree/main/docs">
  Auto-generated docs for every `compass` subcommand.
</Card>

***

<CardGroup cols={2}>
  <Card title="Coding Assistant" icon="robot" href="/v2/Agents/Coding-Assistant">
    Want an AI assistant to write the integration for you? Point it at Compass's LLM-optimized docs.
  </Card>

  <Card title="API Reference" icon="code" href="/v2/api-reference">
    The REST endpoints the CLI wraps. Useful for understanding what each subcommand does on the wire.
  </Card>
</CardGroup>