Alpaca CLI

Alpaca CLI

Install

Check if already installed:

alpaca version

If not installed:

go install github.com/alpacahq/cli/cmd/alpaca@latest

Authentication

Paper trading is the default. alpaca profile login uses OAuth and is paper-only. For live trading, use API keys: alpaca profile login --api-key --live.

Interactive login (stores credentials on disk)

alpaca profile login

Credentials are stored in ~/.config/alpaca/profiles/ with 0600 permissions.

The embedded OAuth client ID and secret are public native-app identifiers, not security credentials. OAuth access is gated by browser consent plus redirect/state validation, and remains paper-only until the flow is hardened with PKCE or Device Authorization Grant.

Environment variables (for scripts, CI, agents)

No secrets touch disk. Preferred for automation:

export ALPACA_API_KEY=PK...
export ALPACA_SECRET_KEY=...

Env API keys default to paper trading. For live, set ALPACA_LIVE_TRADE=true.

When env API keys are set, they are the authoritative credentials - any profile on disk is ignored. OAuth tokens cannot be set via env var; use alpaca profile login to store them in a profile.

Multiple profiles

alpaca profile login --name paper              # OAuth, paper (default)
alpaca profile login --api-key --name live --live  # API keys, live trading
alpaca profile switch live                      # switch active profile
alpaca doctor                                   # show active profile + connectivity

Verify installation

alpaca version
alpaca clock --quiet

If authenticated, also verify credentials work:

alpaca account get --quiet

Exit code 0 = success, 2 = auth error.

Agent and automation usage

API commands are non-interactive once credentials are configured.

Auth and setup commands may still prompt or open a browser:

• alpaca profile login opens a browser for OAuth and may prompt for scopes on a TTY.
• alpaca profile login --api-key prompts for missing credentials unless --key and --secret are provided.
• For unattended workflows, prefer environment variables over alpaca profile login.

Always use --quiet

JSON is the default output format. --quiet suppresses all non-data output (warnings, hints). Use it for machine-readable results:

alpaca position list --quiet
alpaca data latest-trade --symbol AAPL --quiet

Or set it once via environment variable so every invocation is quiet:

export ALPACA_QUIET=1
alpaca position list

Structured errors on stderr

Errors are always JSON on stderr:

{"error":"rate limited","code":0,"status":429,"hint":"Rate limited. Reduce request frequency or add delays between calls."}

Exit codes

Dry run

Preview an order without submitting:

alpaca order submit --symbol AAPL --side buy --qty 10 --type limit --limit-price 185.00 --dry-run

Pipe JSON payloads

echo '{"symbol":"AAPL","qty":"1","side":"buy","type":"market","time_in_force":"day"}' \
  | alpaca api POST /v2/orders

Idempotent order submission

Always pass --client-order-id when submitting orders. The API rejects duplicates (409), preventing double-orders on ambiguous failures:

CLIENT_ORDER_ID="$(uuidgen)"
alpaca order submit --symbol AAPL --side buy --qty 10 --type market --client-order-id "$CLIENT_ORDER_ID" --quiet

On failure or timeout, check before retrying:

alpaca order get-by-client-id --client-order-id "$CLIENT_ORDER_ID" --quiet

If the order is returned, it went through - do not resubmit. If 404 (exit code 1), retry is safe.

Resilience

The CLI retries on 429 and 5xx with exponential backoff (max 3 attempts). Retry-After headers are respected.

Debug API calls

alpaca account get --verbose   # one-line request/response summary on stderr
alpaca account get --trace     # timing breakdown (DNS, TLS, TTFB) on stderr
alpaca account get --debug     # full headers and bodies on stderr

Credentials are always scrubbed from debug output.

Filter JSON output

alpaca position list --jq '.[0].symbol'
alpaca order list --jq '[.[] | {id, symbol, side, qty}]'

--jq applies a jq expression to the JSON output without requiring an external jq install.

Environment variables

Credential precedence

Credentials resolve as an atomic bundle (no field-level mixing). First complete source wins:

1. ALPACA_API_KEY + ALPACA_SECRET_KEY together -> env API keys
2. Profile access_token -> OAuth from active profile
3. Profile api_key + secret_key -> API keys from active profile

A partial env bundle (only one of the two) falls through to the profile. Env API keys always beat anything in a profile. OAuth tokens are not readable from env - use alpaca profile login.

Paper vs live resolves independently: ALPACA_LIVE_TRADE > profile live_trade > paper default. Env-sourced credentials ignore the profile's live_trade field and default to paper unless ALPACA_LIVE_TRADE=true opts into live. Agents should set ALPACA_LIVE_TRADE=true explicitly when live trading is intended; any other value (including false) keeps you on paper.