Command-line interface for the Compass API.
Compass API: Compass Labs DeFi API
curl -fsSL https://raw.githubusercontent.com/CompassLabs/cli/main/scripts/install.sh | bashiwr -useb https://raw.githubusercontent.com/CompassLabs/cli/main/scripts/install.ps1 | iexAlternatively, install directly via Go:
go install github.com/CompassLabs/cli/cmd/compass@latestDownload pre-built binaries for your platform from the releases page.
Shell completions are available for Bash, Zsh, Fish, and PowerShell.
# Add to ~/.bashrc:
source <(compass completion bash)
# Or install permanently:
compass completion bash > /etc/bash_completion.d/compass# Add to ~/.zshrc:
source <(compass completion zsh)
# Or install permanently:
compass completion zsh > "${fpath[1]}/_compass"compass completion fish | source
# Or install permanently:
compass completion fish > ~/.config/fish/completions/compass.fishcompass completion powershell | Out-String | Invoke-Expressioncompass 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 credentials can be configured in four ways (in order of priority):
Pass credentials directly as flags to any command:
compass --api-key-auth <value> <command> [arguments]Set credentials via environment variables:
| Variable | Description |
|---|---|
COMPASS_API_KEY_AUTH |
Your Compass API Key. Get your key here. |
Credentials are stored securely in your operating system's keychain when you run:
compass configureSecret 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.
Run the interactive configure command to store non-secret settings:
compass configureConfiguration is stored in ~/.config/compass/config.yaml.
Available commands
gas-sponsorship-prepare- Prepare gas-sponsored transactiongas-sponsorship-approve-transfer- Approve token transfer
earn-positions- List earn positionsearn-positions-all- List earn positions across all chainsearn-vaults- List vaultsearn-aave-markets- List aave marketsearn-pendle-markets- List pendle marketsearn-balances- Get token balancesearn-create-account- Create earn accountearn-transfer- Transfer tokens to/from accountearn-manage- Manage earn positionearn-swap- Swap tokens within Earn Accountearn-bundle- Execute multiple earn actions
credit-positions- List credit positionscredit-balances- Get credit account token balancescredit-create-account- Create credit accountcredit-borrow- Borrow against collateralcredit-transfer- Transfer tokens to/from Credit Accountcredit-repay- Repay debt and withdraw collateralcredit-bundle- Execute multiple credit actions
global-markets-perps-opportunities- List global markets perps marketsglobal-markets-perps-positions- List global markets perps positionsglobal-markets-perps-deposit- Deposit USDC to global markets perps accountglobal-markets-perps-withdraw- Withdraw USDC from global markets perps accountglobal-markets-perps-market-order- Place market orderglobal-markets-perps-limit-order- Place limit orderglobal-markets-perps-cancel-order- Cancel orderglobal-markets-perps-execute- Execute signed actionglobal-markets-perps-approve-builder-fee- Approve builder feeglobal-markets-perps-enable-unified-account- Enable unified account modeglobal-markets-perps-ensure-leverage- Ensure 1x cross leverage
tokenized-assets-markets- List tokenized equity marketstokenized-assets-markets-symbol- Get a single markettokenized-assets-positions- Get tokenized-asset positions for a wallettokenized-assets-order-order-hash- Get order statustokenized-assets-create-account- Create a Tokenized Assets Accounttokenized-assets-quote- Preview a buy/sell quotetokenized-assets-order- Build a buy/sell ordertokenized-assets-order-submit- Submit a signed ordertokenized-assets-order-order-hash-cancel- Cancel an unfilled order
Operations that accept a request body support three input methods, with a clear priority chain:
compass <command> --name "Jane" --age 30Provide 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"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>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 |
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
Every command supports a --output-format flag that controls how the response is rendered to stdout.
| 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'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)'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.
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 |
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"
fiThe CLI includes two diagnostic flags available on all commands:
Preview what would be sent without making any network calls:
compass <command> --dry-runOutput 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.
Log request and response diagnostics while running normally:
compass <command> --debugDebug 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.
If both --dry-run and --debug are set, --dry-run takes precedence and no network calls are made.
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.
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.
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.
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.
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.
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.
- 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-keyflag: the auth flag is--api-key-auth(single token). COMPASS_API_KEYdoesn't work; the env var isCOMPASS_API_KEY_AUTH.
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.
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.