gem-hunter

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

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.

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

# Homebrew
brew install alpacahq/tap/cli

# 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

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.

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 fixed-income, data meta, data screener, data news
• Utilities: profile, api, doctor, update, version, completion

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

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:

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

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.

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.

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.

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:

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

• CLI issues: Bugs, feature requests, or questions specific to this CLI → GitHub Issues.
• General Alpaca support & API discussion: Account questions, platform issues, or broader API topics → Alpaca Community Forum.
• Slack community: Chat with other developers and the Alpaca community on Slack (join here).

Apache 2.0