> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fcontext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI
> 使用 fcontext terminal CLI 访问 Financial Context 市场数据
在终端中使用 `fcontext` 查询 Financial Context 市场数据、管理登录，并为脚本或 agent 输出 JSON。
CLI 默认连接 Financial Context：
```text theme={null}
https://openapi.fcontext.com
```
命令会调用 `/api/market-data/*` 下的只读市场数据接口。当前 CLI 聚焦美股数据：标的必须使用 `CODE.US` 格式，market 筛选条件必须为 `US`。
## 命令基础
两个命令名都可以使用。`fctx` 是 `fcontext` 的短别名，支持相同的子命令、flag、输出格式和 schema。
```bash theme={null}
fcontext quote AAPL.US MSFT.US --format json
fctx quote AAPL.US MSFT.US --format json
```
## 安装
从 Aitaport tap 安装 `fcontext-terminal` cask：
```bash theme={null}
brew install --cask aitaport/tap/fcontext-terminal
```
使用托管 shell 安装脚本：
```bash theme={null}
curl -sSL https://fcontext.com/fcontext/fcontext-terminal/install | sh
```
使用托管的 `fcontext.json` Scoop manifest 安装：
```powershell theme={null}
scoop install https://fcontext.com/fcontext/fcontext-terminal/fcontext.json
```
使用托管 PowerShell 安装脚本：
```powershell theme={null}
iwr https://fcontext.com/fcontext/fcontext-terminal/install.ps1 | iex
```
Release artifact 使用 terminal 项目的 `fcontext-terminal-*` 包名，包括
`fcontext-terminal-darwin-amd64.tar.gz`、`fcontext-terminal-darwin-arm64.tar.gz`、
`fcontext-terminal-linux-musl-amd64.tar.gz`、`fcontext-terminal-linux-musl-arm64.tar.gz`
和 `fcontext-terminal-windows-amd64.zip`。shell 和 PowerShell 安装器会下载匹配的归档文件，
校验 `.sha256` checksum，并安装 `fcontext` 和 `fctx`。
## 认证
管理 CLI 认证：登录、登出和查看本地 token 状态。
### OAuth 2.0 登录
使用 OAuth 2.0 authorization-code flow 登录。该方式适用于本地终端、SSH session 和 headless server，因为 CLI 会打印授权 URL 和下一条需要执行的命令。
```bash theme={null}
fcontext auth login
```
在任意浏览器打开打印出的授权 URL，完成授权后复制返回的 code 并兑换：
```bash theme={null}
fcontext auth login --auth-code YOUR_CODE
```
CLI 会把 token 存储为本地 fcontext 配置目录中的 `oauth-token.json`。后续命令会自动复用该 token。
### Authorization Code
如果当前机器无法使用浏览器，可以从 Financial Context Connect 生成一次性 authorization code 并直接兑换：
```bash theme={null}
fcontext auth login --auth-code YOUR_CODE
```
### 登出
清除本地存储的 OAuth token。下一次认证命令会要求重新登录。
```bash theme={null}
fcontext auth logout
```
### 认证状态
查看当前 base URL 和登录状态。
```bash theme={null}
fcontext auth status
fcontext auth status --format json
```
## 检查
验证登录和 Financial Context API 连通性，无需依赖活跃市场时段。报告会包含 endpoint 状态和延迟。
```bash theme={null}
fcontext check
fcontext check --format json
fctx check --format json
```
## 更新
下载并运行官方安装脚本，将当前 CLI binary 替换为最新版本。
```bash theme={null}
fcontext update
fctx update
```
## 首批命令
```bash theme={null}
# 实时行情
fcontext quote AAPL.US MSFT.US
# 短别名
fctx quote AAPL.US MSFT.US
# 面向脚本和 agent 的 JSON 输出
fcontext quote AAPL.US MSFT.US --format json
# 证券静态信息
fcontext static AAPL.US MSFT.US
# 日 K 线
fcontext kline AAPL.US --period day --count 100
# 按日期范围查询历史 K 线
fcontext kline history AAPL.US --start 2024-01-01 --end 2024-12-31
```
## 市场数据
```bash theme={null}
fcontext market-status
fcontext top-movers --market US --sort hot --count 20
fcontext market-temp US
fcontext market-temp US --history --start 2024-01-01 --end 2024-12-31
fcontext trading session
fcontext trading days US --start 2026-01-01 --end 2026-01-31
fcontext security-list US
```
使用 `fear-greed` 查看 Fear & Greed Index。它是一项市场情绪指标，用从 extreme fear 到 extreme greed 的刻度概括投资者风险偏好：
```bash theme={null}
fcontext fear-greed
fcontext fear-greed --history-count 90 --indicator-history-count 10 --format json
```
## 公司数据
```bash theme={null}
fcontext company AAPL.US
fcontext fundamental-compare AAPL.US
fcontext compare AAPL.US MSFT.US NVDA.US --currency USD
fcontext consensus AAPL.US
fcontext dividend AAPL.US
fcontext forecast-eps AAPL.US
fcontext insider-trades AAPL.US --count 20
fcontext institution-rating AAPL.US
fcontext institution-rating detail AAPL.US
fcontext operating AAPL.US
fcontext shareholder AAPL.US
fcontext shareholder AAPL.US --top --periods 4
fcontext valuation AAPL.US
fcontext valuation AAPL.US --history
```
## 新闻与事件
```bash theme={null}
fcontext news AAPL.US
fcontext filing AAPL.US
fcontext topic AAPL.US
fcontext finance-calendar report --market US
fcontext finance-calendar dividend --market US
```
## 交易活动
```bash theme={null}
fcontext trades AAPL.US --count 50
fcontext trade-stats AAPL.US
fcontext short-positions AAPL.US
fcontext short-trades AAPL.US
```
## 选股器
```bash theme={null}
fcontext screener strategies --market US
fcontext screener mine --market US
fcontext screener strategy 19
fcontext screener run 19 --count 20
fcontext screener filter pettm:10:50 roe:5: --market US
fcontext screener indicators
```
## 直接访问 Endpoint
当某个受支持的只读 endpoint 还没有专用命令时，可以使用 `api get`：
```bash theme={null}
fcontext api get /api/market-data/market/status --format json
```
CLI 会在发送请求前拒绝绝对 URL、streaming endpoint、非美股 market filter，以及不支持的账户或交易路径。
## 面向 Agent 的输出
每个命令都支持 JSON 输出：
```bash theme={null}
fcontext company AAPL.US --format json
```
使用 `--schema` 打印机器可读的响应 schema：
```bash theme={null}
fcontext company --schema
fcontext quote --schema
fctx quote --schema
```
生成 shell completions：
```bash theme={null}
fcontext completion zsh > ~/.zfunc/_fcontext
fcontext completion bash > ~/.local/share/bash-completion/completions/fcontext
fcontext completion fish > ~/.config/fish/completions/fcontext.fish
```
## 故障排查
| 问题 | 检查项 |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `Missing fcontext credentials` | 运行 `fcontext auth login`，或用 `fcontext auth login --auth-code YOUR_CODE` 兑换 authorization code。 |
| `fcontext API error (401)` | 运行 `fcontext auth status`，如果本地 token 缺失或过期，请用 `fcontext auth login` 重新登录。 |
| 非美股 symbol 被拒绝 | 使用 `AAPL.US` 这类 symbol；CLI 有意不暴露非美股市场。 |
| 需要请求详情 | 添加 `--verbose`，将请求 URL 和耗时打印到 stderr。 |