cli

README

cli

Command-line interface for the Compass API.

Summary

Compass API: Compass Labs DeFi API

Table of Contents

• cli
  • CLI Installation
  • Shell Completion
  • CLI Example Usage
  • Authentication
  • Available Commands
  • Request Body Input
  • Server Selection
  • Output Formats
  • Error Handling
  • Diagnostics
  • Common Pitfalls
• Development
  • Maturity
  • Contributions

CLI Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/CompassLabs/cli/main/scripts/install.sh | bash

Quick Install (Windows PowerShell)

iwr -useb https://raw.githubusercontent.com/CompassLabs/cli/main/scripts/install.ps1 | iex

Go Install

Alternatively, install directly via Go:

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

Manual Download

Download pre-built binaries for your platform from the releases page.

Shell Completion

Shell completions are available for Bash, Zsh, Fish, and PowerShell.

Bash

# Add to ~/.bashrc:
source <(compass completion bash)

# Or install permanently:
compass completion bash > /etc/bash_completion.d/compass

Zsh

# Add to ~/.zshrc:
source <(compass completion zsh)

# Or install permanently:
compass completion zsh > "${fpath[1]}/_compass"

Fish

compass completion fish | source

# Or install permanently:
compass completion fish > ~/.config/fish/completions/compass.fish

PowerShell

compass completion powershell | Out-String | Invoke-Expression

CLI Example Usage

Example

compass gas-sponsorship gas-sponsorship-prepare --api-key-auth test_api_key --owner 0xCE1A77F0abff993d6d3D04d44b70831c6924fb40 --chain arbitrum --eip-712 '{"domain":{"name":"USD Coin","version":"2","chainId":42161,"verifyingContract":"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"},"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"version","type":"string"},{"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}],"Permit":[{"name":"owner","type":"address"},{"name":"spender","type":"address"},{"name":"value","type":"uint256"},{"name":"nonce","type":"uint256"},{"name":"deadline","type":"uint256"}]},"primaryType":"Permit","message":{"owner":"0xCE1A77F0abff993d6d3D04d44b70831c6924fb40","spender":"0x000000000022D473030F116dDEE9F6B43aC78BA3","value":"115792089237316195423570985008687907853269984665640564039457584007913129639935","nonce":"0","deadline":"1762269774"\x7d\x7d' --signature 0x160d2709ae195f591daa33ad6ab1fb18b8762a39d8c4466c4cbe95cf6881fc3d54d469710ef0e7fd64ecff47c1ba5741d7254903bfaebdacea5aa8289f81ba9a1c --sender 0x02122Ac49b0Be2e0eAD957F2D080805A0127Aa9d

Authentication

Authentication credentials can be configured in four ways (in order of priority):

1. Command-line flags

Pass credentials directly as flags to any command:

compass --api-key-auth <value> <command> [arguments]

2. Environment variables

Set credentials via environment variables:

Variable	Description
COMPASS_API_KEY_AUTH	Your Compass API Key. Get your key here.

3. OS Keychain (recommended for workstations)

Credentials are stored securely in your operating system's keychain when you run:

compass configure

Secret credentials (tokens, API keys, passwords) are automatically stored in:

• macOS: Keychain
• Linux: GNOME Keyring / KWallet (via D-Bus Secret Service)
• Windows: Windows Credential Locker

If no keychain is available (e.g., in CI environments), credentials fall back to the config file.

4. Configuration file

Run the interactive configure command to store non-secret settings:

compass configure

Configuration is stored in ~/.config/compass/config.yaml.

Available Commands

Available commands

gas-sponsorship

• gas-sponsorship-prepare - Prepare gas-sponsored transaction
• gas-sponsorship-approve-transfer - Approve token transfer

earn

• earn-positions - List earn positions
• earn-positions-all - List earn positions across all chains
• earn-vaults - List vaults
• earn-aave-markets - List aave markets
• earn-pendle-markets - List pendle markets
• earn-balances - Get token balances
• earn-create-account - Create earn account
• earn-transfer - Transfer tokens to/from account
• earn-manage - Manage earn position
• earn-swap - Swap tokens within Earn Account
• earn-bundle - Execute multiple earn actions

credit

• credit-positions - List credit positions
• credit-balances - Get credit account token balances
• credit-create-account - Create credit account
• credit-borrow - Borrow against collateral
• credit-transfer - Transfer tokens to/from Credit Account
• credit-repay - Repay debt and withdraw collateral
• credit-bundle - Execute multiple credit actions

global-markets-perps

• global-markets-perps-opportunities - List global markets perps markets
• global-markets-perps-positions - List global markets perps positions
• global-markets-perps-deposit - Deposit USDC to global markets perps account
• global-markets-perps-withdraw - Withdraw USDC from global markets perps account
• global-markets-perps-market-order - Place market order
• global-markets-perps-limit-order - Place limit order
• global-markets-perps-cancel-order - Cancel order
• global-markets-perps-execute - Execute signed action
• global-markets-perps-approve-builder-fee - Approve builder fee
• global-markets-perps-enable-unified-account - Enable unified account mode
• global-markets-perps-ensure-leverage - Ensure 1x cross leverage

tokenized-assets

• tokenized-assets-markets - List tokenized equity markets
• tokenized-assets-markets-symbol - Get a single market
• tokenized-assets-positions - Get tokenized-asset positions for a wallet
• tokenized-assets-order-order-hash - Get order status
• tokenized-assets-create-account - Create a Tokenized Assets Account
• tokenized-assets-quote - Preview a buy/sell quote
• tokenized-assets-order - Build a buy/sell order
• tokenized-assets-order-submit - Submit a signed order
• tokenized-assets-order-order-hash-cancel - Cancel an unfilled order

Request Body Input

Operations that accept a request body support three input methods, with a clear priority chain:

Individual flags (highest priority)

compass <command> --name "Jane" --age 30

--body flag

Provide the entire request body as a JSON string:

compass <command> --body '{"name": "John", "age": 30}'

Individual flags override --body values:

# Result: {name: "Jane", age: 30}
compass <command> --body '{"name": "John", "age": 30}' --name "Jane"

Stdin piping (lowest priority)

Pipe JSON into any command that accepts a request body:

echo '{"name": "John", "age": 30}' | compass <command>

Individual flags override stdin values:

# Result: {name: "Jane", age: 30}
echo '{"name": "John", "age": 30}' | compass <command> --name "Jane"

This is useful for chaining commands, reading from files, or scripting:

# Read body from a file
compass <command> < request.json

# Pipe from another command
curl -s https://example.com/data.json | compass <command>

Priority

When multiple input methods are used, the priority is:

Priority	Source	Description
1 (highest)	Individual flags	--name "Jane" always wins
2	--body flag	Whole-body JSON via flag
3 (lowest)	Stdin	Piped JSON input

Server Selection

Override Server URL

Use --server-url to override the server URL entirely, bypassing any named or indexed server selection:

compass --server-url https://custom-api.example.com <command> [arguments]

Precedence: --server-url > --server > default

Output Formats

Every command supports a --output-format flag that controls how the response is rendered to stdout.

Available formats

Format	Flag	Description
Pretty	--output-format pretty (default)	Aligned key-value pairs with color, nested indentation. Human-readable at a glance.
JSON	--output-format json	JSON output. Passthrough when the response is already JSON (preserves original field order and numeric precision). Falls back to typed marshaling otherwise.
YAML	--output-format yaml	YAML output via standard marshaling.
Table	--output-format table	Tabular output for array responses.
TOON	--output-format toon	Token-Oriented Object Notation — a compact, line-oriented format that typically uses 30–60% fewer tokens than JSON. Well-suited for piping responses into LLM prompts.

# Default pretty output
compass <command>

# Machine-readable JSON
compass <command> --output-format json

# TOON for LLM-friendly compact output
compass <command> --output-format toon

# Pipe JSON to jq without using --output-format
compass <command> --output-format json | jq '.fieldName'

jq filtering

Use --jq to filter or transform the response inline using a jq expression. This always outputs JSON and overrides --output-format:

# Extract a single field
compass <command> --jq '.name'

# Filter an array
compass <command> --jq '.items[] | select(.active == true)'

Color control

Use --color to control terminal colors:

Value	Behavior
auto (default)	Color when stdout is a TTY, plain text otherwise
always	Always colorize
never	Never colorize

The NO_COLOR and FORCE_COLOR environment variables are also respected.

Streaming and pagination

When using --all (pagination) or streaming operations, output is written incrementally as items arrive:

Format	Streaming behavior
json	One compact JSON object per line (NDJSON)
yaml	YAML documents separated by ---
toon	One TOON-encoded object per block, separated by blank lines
pretty (default)	Pretty-printed items separated by blank lines

Error Handling

The CLI uses standard exit codes to indicate success or failure:

Exit Code	Meaning
0	Success
1	Error (API error, invalid input, etc.)

On success, the response data is printed to stdout as JSON. On failure, error details are printed to stderr.

# Capture output and handle errors
compass ... > output.json 2> error.log
if [ $? -ne 0 ]; then
  echo "Error occurred, see error.log"
fi

Diagnostics

The CLI includes two diagnostic flags available on all commands:

Dry Run

Preview what would be sent without making any network calls:

compass <command> --dry-run

Output goes to stderr and includes:

• HTTP method and URL
• Request headers (sensitive values redacted)
• Request body preview (sensitive fields redacted)

The command exits successfully without contacting the API. This is useful for verifying request construction before executing.

Debug

Log request and response diagnostics while running normally:

compass <command> --debug

Debug output goes to stderr and includes:

• Request method, URL, headers, and body preview
• Response status, headers, and body preview
• Transport errors (if any)

The command still executes normally and produces its regular output on stdout.

Flag Precedence

If both --dry-run and --debug are set, --dry-run takes precedence and no network calls are made.

Security

Sensitive information is automatically redacted in diagnostic output:

• Headers: Authorization, Cookie, Set-Cookie, X-API-Key, and other security headers show [REDACTED]
• Body: JSON fields named password, secret, token, api_key, client_secret, etc. show [REDACTED]

Diagnostic output should still be treated as potentially sensitive operational data.

Common Pitfalls

These are real footguns surfaced during prod testing. AI coding agents should read this section before writing CLI invocations — most of these errors are not obvious from the per-command help text.

Some optional flags require JSON-quoted values

Flags whose help text reads as a regular string but that are implemented as JSON-encoded query parameters require JSON-quoted values. Only optional string-typed query params are affected; optional numeric flags (e.g., --min-tvl-usd, --limit) work plain because the JSON parser accepts bare numbers. Affected today:

Command	Flag(s)
earn earn-vaults	--chain, --asset-symbol
earn earn-aave-markets	--chain
earn earn-pendle-markets	--chain, --underlying-symbol
tokenized-assets tokenized-assets-markets	--category, --search
tokenized-assets tokenized-assets-markets-symbol	--interval, --range
traditional-investing traditional-investing-opportunities	--category
traditional-investing traditional-investing-positions	--asset

Example:

# Wrong: --chain base       → invalid character 'b' looking for beginning of value
# Right: --chain '"base"'

Symptom: an error like invalid value for --chain: error unmarshalling json response body: invalid character 'b' looking for beginning of value. The phrase "response body" is misleading — this is flag parsing, not an HTTP error.

Workaround: wrap the value in JSON-quoted form ('"value"' in zsh/bash). Or, if the flag is optional, omit it entirely.

Why: Speakeasy generates these as FlagKindJSON because they're optional query parameters; the generator does json.Unmarshal on the raw input. Required enum/string flags use a different code path and accept plain values normally. Tracked for upstream/overlay fix.

-o table does not unwrap response envelopes

Endpoints that return paginated lists wrap the array in an envelope, e.g. earn-vaults returns { total, offset, limit, vaults: [...] }. --output-format table renders the envelope, not the array.

# Tiny scalar table — not what you want
compass earn earn-vaults --order-by tvl_usd -o table

# Drill into the array (output is JSON; --jq forces JSON regardless of -o)
compass earn earn-vaults --order-by tvl_usd --jq '.vaults'

The same pattern applies to other list endpoints (earn-aave-markets, tokenized-assets-markets, etc.). If you want a table of the inner array specifically, that's not supported in a single command today — pipe the JSON result through another tool, or just consume the JSON.

Flag metavars can be misleading

Some flags display unusual metavars in --help listings — these are placeholders inferred from the OpenAPI example, not part of the syntax:

--action venue              # "venue" is a metavar; pass DEPOSIT or WITHDRAW
--gas-sponsorship true      # "true" is a metavar; the flag is a bool
--amount from_token         # "from_token" is a metavar; pass a number string like "100"
--from-token TSLAon         # "TSLAon" is an example value; pass any token symbol or address
--to-token from_token       # "from_token" is a metavar; pass any token symbol or address

Trust the Description column over the metavar.

Command names contain "stutter"

Several commands repeat their group name: compass earn earn-vaults, compass credit credit-transfer, etc. This is by current design (the OpenAPI tag and operationId both include the domain word). When piping --help output or relying on tab completion, expect the duplicated prefix. The full command tree is in docs/compass.md.

Other quirks

• Line continuations: compass <cmd> \ followed by a trailing space (especially after pasting) breaks zsh — strip trailing whitespace or use a one-liner.
• No --api-key / --api-key-auth-key flag: the auth flag is --api-key-auth (single token).
• COMPASS_API_KEY doesn't work; the env var is COMPASS_API_KEY_AUTH.

Development

Maturity

This CLI is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this CLI, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

CLI Created by Speakeasy