CLI

Install, authenticate, and use the Surf CLI

CLI

Install

curl -fsSL https://downloads.asksurf.ai/cli/releases/install.sh | sh

Installs the surf binary to ~/.surf/bin and stores config under ~/.surf/. No sudo required.

To install a specific version:

curl -fsSL https://downloads.asksurf.ai/cli/releases/install.sh | sh -s v0.1.3

The CLI is open source at github.com/asksurf-ai/surf-cli. To build from source (Go 1.25+):

go install github.com/asksurf-ai/surf-cli/cmd/surf@latest

Authenticate

No API key required to try it out. Every IP gets 30 free credits per day — just install and start querying.

For full access, get your API key from agents.asksurf.ai (sign in → Dashboard → Generate API Key), then save it:

# Option 1: save the key (prefers OS keychain, falls back to ~/.surf/config.json)
surf auth --api-key sk-your-key-here
 
# Option 2: environment variable (per-session, takes precedence over saved key)
export SURF_API_KEY=sk-your-key-here

Check status or clear a saved key:

surf auth          # show current key source and masked value
surf auth --clear  # remove from both keychain and file

Keys are resolved in this order: SURF_API_KEY env → OS keychain (macOS Keychain, Linux secret-service, Windows Credential Manager) → ~/.surf/config.json.

Discover Commands

Re-fetch the latest OpenAPI spec and list all available operations:

surf sync                 # pull latest API spec, refresh command list
surf list-operations -g   # grouped by category

Inspect any command before using it:

surf market-price --help
surf wallet-detail --help
surf search-project --help

Other built-ins: surf version (or -v), surf auth, surf help.

Common Examples

# Market data
surf market-price --symbol BTC
 
# Wallet intelligence
surf wallet-detail --address 0x1234...
 
# Social lookup
surf social-user --handle vitalikbuterin
 
# Project search
surf search-project --q aave

For scripts and agents, use structured output:

surf market-price --symbol BTC -o json -f body.data
surf wallet-detail --address 0x1234... -o json -f body.data
surf social-user --handle vitalikbuterin -o json -f body.data

Command Conventions

Pattern	Recommendation
Flags	Use kebab-case CLI flags such as `--time-range` and `--token-address`
Search	Use `--q`, not `-q`, for search parameters
Chains	Use canonical names such as `ethereum`, `solana`, `base`, and `arbitrum`
Discovery	Prefer `surf <command> --help` to inspect enums, defaults, and response fields
Structured output	Use `-o json` for scripts, tooling, and agent workflows

Environment Variables

Variable	Purpose	Default
`SURF_API_KEY`	API key (overrides keychain and file)	—
`SURF_API_BASE_URL`	Override the API gateway base URL	`https://api.asksurf.ai/gateway/v1`

What You Can Query

The CLI covers the same core domains exposed in the Surf Data API:

Market data and technical indicators
Exchange data such as ticker, order book depth, funding history, and candlesticks
Wallet balances, transfers, protocol positions, and net worth
Project profiles and DeFi metrics
Token holders, transfers, DEX trades, and unlock schedules
Prediction markets across Polymarket and Kalshi
On-chain transaction lookups, structured query, SQL, and gas prices
News, web fetch, and unified search