核心用法
alpaca-py-cli 是一款基于 Python 的 CLI 工具，封装了 Alpaca Markets 官方 SDK，提供完整的程序化交易能力。用户通过 alpaca 命令即可完成从行情查询、订单执行到持仓管理的全流程操作。
主要功能模块：
- 账户与市场信息：
alpaca account查看账户余额与 P&L；alpaca clock检查市场开闭状态；alpaca calendar查看交易日历 - 行情数据：
alpaca quote <symbols>获取实时买卖报价（支持多标的批量查询） - 订单管理：
alpaca buy/sell <symbol> <qty>执行市价单；alpaca orders查看订单状态；alpaca cancel/close取消订单或平仓 - 持仓与历史：
alpaca positions显示当前持仓及浮动盈亏；alpaca history查看指定周期的组合净值变化
交易模式：
- Paper Trading（推荐）：虚拟资金 $100,000，零风险测试策略
- Live Trading：真实资金，需先在 Paper 环境充分验证
配置方式：运行 alpaca auth 交互式向导，自动将 API Key/Secret 写入 shell 配置文件（支持 zsh/bash）。也可手动设置环境变量 ALPACA_API_KEY、ALPACA_SECRET_KEY、ALPACA_PAPER。
显著优点
1. 极低上手门槛：单行命令完成复杂操作，无需编写 Python 脚本即可执行交易
2. 安全凭证管理：auth 命令隐藏输入 Secret Key，避免终端历史泄露风险
3. 双模式无缝切换：同一套 CLI 命令支持 Paper/Live，仅需切换 API Key 和 ALPACA_PAPER 变量
4. 可视化状态指示：订单状态使用 emoji（⏳✓✗），市场状态用 🔴🟢，提升可读性
5. 丰富的时间序列分析：支持多周期（1D/1W/1M/3M/1Y）和多粒度（1Min-1Day）的历史收益查询
6. 完善的防护机制：close-all 需确认、cancel-all 一键撤单，降低误操作风险
潜在缺点与局限性
1. 订单类型有限：当前仅支持市价单（market order），缺少限价单、止损单、OCO 等高级订单类型
2. 行情时效性：非交易时段报价可能不完整或滞后，工具明确提示需在开盘时间（9:30-16:00 ET）使用
3. macOS 兼容性问题：系统 Python 可能因 LibreSSL 触发 urllib3 警告，需改用 Homebrew Python 3.11+
4. 单一经纪商依赖：仅支持 Alpaca Markets，无法对接其他券商或交易所
5. 无策略回测功能：仅提供历史净值查询，缺乏内置的策略回测框架
适合人群
- 量化交易初学者：希望用 CLI 快速验证交易想法，无需搭建复杂系统
- 个人投资者：需要轻量级工具监控持仓、执行简单交易指令
- 开发者/自动化测试：将交易命令集成到 shell 脚本或 CI/CD 流程中
- Paper Trading 用户：在零风险环境中练习程序化交易逻辑
常规风险
- API 密钥泄露风险：密钥存储于 shell 配置文件，若环境未妥善隔离可能被其他进程读取
- 实盘误操作风险：Paper/Live 模式切换依赖环境变量，配置错误可能导致真实资金交易
- 市场风险：市价单在波动剧烈时可能以不利价格成交；非交易时段订单将被队列延迟执行
- 依赖维护风险：
alpaca-py和pytz包的版本更新可能引入 breaking changes - 流动性风险：小盘股或加密货币在特定时段可能出现报价缺失或滑点扩大
> ⚠️ 关键建议：首次使用务必在 Paper 模式完成完整交易流程验证；定期检查 alpaca orders 确认订单状态；大额操作前执行 alpaca account 核对可用资金。