Alpaca CLI

CLI for the Alpaca Trading API. Trade stocks and crypto, access market data, and manage your account from the command line.

Warning

Alpha Preview - This CLI is under active development. Commands, flags, and output formats may change or be removed without notice between releases. Do not depend on current behavior in production workflows.

Built For Agents

Alpaca CLI is designed for AI agents, scripts, and automation pipelines. It is not an interactive trading terminal: there are no confirmation prompts, "are you sure?" dialogs, or interactive guardrails. Every command executes immediately.

Destructive commands are truly destructive:

• alpaca position close-all liquidates your entire portfolio.
• alpaca order cancel-all cancels every open order without listing them first.
• alpaca locate create requests shares for a short sale and may incur locate fees.

Paper trading is the default. Live trading requires an explicit opt-in.

Install

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

# Homebrew
brew install alpacahq/tap/cli

Quick Start

# Authenticate with paper trading OAuth
alpaca profile login

# Check your account
alpaca account get

# Submit an order
alpaca order submit --symbol AAPL --side buy --qty 10 --type market

# List positions and open orders
alpaca position list
alpaca order list --status open

# Get market data
alpaca data bars --symbol AAPL --start 2025-01-01 --timeframe 1Day

# Check if the market is open
alpaca clock

Authentication

alpaca profile login opens a browser for OAuth authorization and stores a paper trading profile in ~/.config/alpaca/profiles/ with restricted file permissions.

alpaca profile login                              # OAuth, paper trading
alpaca profile login --api-key                    # API key and secret, paper trading
alpaca profile login --api-key --live             # API key and secret, live trading
alpaca profile login --api-key --name prod --live # Named live profile
alpaca profile switch prod                        # Switch active profile

OAuth is currently paper-only. Live trading requires API keys.

For scripts, CI, and agents, prefer environment variables so secrets do not touch disk:

export ALPACA_API_KEY=PK...
export ALPACA_SECRET_KEY=...
alpaca account get --quiet

Environment API keys default to paper trading. To use live trading:

export ALPACA_LIVE_TRADE=true

Credential lookup uses the first complete credential bundle:

1. ALPACA_API_KEY and ALPACA_SECRET_KEY
2. Profile access_token
3. Profile api_key and secret_key

A partial environment bundle falls through to the active profile. OAuth tokens cannot be supplied through environment variables.

Commands

The CLI is generated from Alpaca OpenAPI specs, so the installed binary is the source of truth for commands, flags, enum completions, validation, and response schemas.

alpaca --help-all              # Full command reference
alpaca order submit --help     # Flags for one command
alpaca order submit --schema   # Response fields without an API call

Top-level command areas include:

• Trading: order, position, option, locate, clock, calendar
• Account and assets: account, asset, watchlist, wallet, corporate-action
• Market data: data, data crypto, data option, data forex, data index, data meta, data screener, data news
• Crypto perpetuals: crypto-perp
• Utilities: profile, api, doctor, update, version, completion

Use alpaca api [METHOD] <path> as a raw escape hatch for direct API requests.

Output

API commands return JSON on stdout by default. They also support CSV output, inline jq filtering, quiet mode, response schemas, and request timeouts.

alpaca position list
alpaca position list --csv
alpaca position list --jq '.[0].symbol'
alpaca order list --quiet
alpaca data bars --symbol AAPL --start 2020-01-01 --timeout 120

Operational commands such as version, doctor, profile, update, completion, and help emit human-readable text. The exception is alpaca update --check, which emits JSON for automation.

Errors are JSON on stderr:

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

Exit codes:

Code	Meaning
0	Success
1	API or general error
2	Authentication error

Configuration

Variable	Description
ALPACA_API_KEY	API key. Must be set with ALPACA_SECRET_KEY.
ALPACA_SECRET_KEY	Secret key. Must be set with ALPACA_API_KEY.
ALPACA_LIVE_TRADE	true routes to live trading. Anything else routes to paper trading.
ALPACA_PROFILE	Profile name to use.
ALPACA_OUTPUT	Default output format: json or csv.
ALPACA_CONFIG_DIR	Config directory. Defaults to ~/.config/alpaca.
ALPACA_QUIET	Suppress non-data output such as warnings, hints, and color.
ALPACA_VERBOSE	Show HTTP request summaries on stderr.
ALPACA_DEBUG	Show HTTP request and response headers and bodies on stderr.
ALPACA_TRACE	Show HTTP timing breakdown on stderr.

Global flags: --csv, --jq, --profile, --verbose, --debug, --trace, --quiet, --schema, --timeout.

Automation Notes

For AI agents, see the alpaca-cli Agent Skill for structured installation, authentication, and usage guidance.

For unattended order submission, pass --client-order-id so retries after ambiguous failures do not create duplicate orders:

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

Use --dry-run to 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 into raw POST and PATCH API requests:

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

The CLI retries 429 and 5xx responses with exponential backoff up to 3 attempts. Retry-After headers are respected.

Diagnostics

alpaca doctor                  # Check config and API connectivity
alpaca account get --verbose   # Request summary on stderr
alpaca account get --trace     # DNS, TLS, TTFB, and total timing on stderr
alpaca account get --debug     # Headers and bodies on stderr

Credentials are always scrubbed from diagnostic output.

Shell Completions

alpaca completion bash
alpaca completion zsh
alpaca completion fish
alpaca completion powershell

Save the generated completion script where your shell expects it, then open a new shell. Enum-valued flags complete with valid values from the OpenAPI specs.

Self-Update

alpaca update          # Check for updates and prompt to install
alpaca update --yes    # Check and install without prompting
alpaca update --check  # Machine-readable update check

Upgrade commands are tailored to the detected install method:

Install method	Upgrade command
Go	go install github.com/alpacahq/cli/cmd/alpaca@latest
Homebrew	brew upgrade alpacahq/tap/cli

Development

The CLI is driven by OpenAPI specs in api/specs/*.json. Do not edit generated files directly. Change the specs or generator, then run make generate.

make build            # Build binary to bin/alpaca
make test             # Run unit tests
make lint             # Run linter
make check            # Lint, test, and build
make test-integration # Run live paper API integration tests
make generate         # Regenerate API clients and command metadata
make spec-update      # Fetch latest OpenAPI specs

Integration tests require paper trading credentials:

export ALPACA_TEST_API_KEY=PK...
export ALPACA_TEST_SECRET_KEY=...
export ALPACA_TEST_BASE_URL=https://paper-api.alpaca.markets # optional
make test-integration

License

Apache 2.0