> ## 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。 |