> ## 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는 US 주식 데이터에 초점을 맞추며, 심볼은 `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
```

## 설치

<Tabs>
  <Tab title="macOS (Homebrew)">
    Aitaport tap에서 `fcontext-terminal` cask를 설치합니다.

    ```bash theme={null}
    brew install --cask aitaport/tap/fcontext-terminal
    ```
  </Tab>

  <Tab title="Linux / macOS (Script)">
    호스팅된 shell 설치 스크립트를 사용합니다.

    ```bash theme={null}
    curl -sSL https://fcontext.com/fcontext/fcontext-terminal/install | sh
    ```
  </Tab>

  <Tab title="Windows (Scoop)">
    호스팅된 `fcontext.json` Scoop manifest에서 설치합니다.

    ```powershell theme={null}
    scoop install https://fcontext.com/fcontext/fcontext-terminal/fcontext.json
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    호스팅된 PowerShell 설치 스크립트를 사용합니다.

    ```powershell theme={null}
    iwr https://fcontext.com/fcontext/fcontext-terminal/install.ps1 | iex
    ```
  </Tab>
</Tabs>

<Note>
  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`를 모두 설치합니다.
</Note>

## 인증

CLI 인증을 관리합니다. 로그인, 로그아웃, 로컬 token 상태 확인을 지원합니다.

### OAuth 2.0 로그인

OAuth 2.0 authorization-code flow로 로그인합니다. CLI가 authorization URL과 다음에 실행할 명령을 출력하므로 로컬 터미널, SSH session, headless server에서 사용할 수 있습니다.

```bash theme={null}
fcontext auth login
```

출력된 authorization 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

# 일봉 캔들
fcontext kline AAPL.US --period day --count 100

# 날짜 범위로 과거 캔들 조회
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
```

## 엔드포인트 직접 접근

전용 명령이 아직 없는 지원되는 읽기 전용 엔드포인트가 필요할 때 `api get`을 사용합니다.

```bash theme={null}
fcontext api get /api/market-data/market/status --format json
```

CLI는 요청을 보내기 전에 절대 URL, streaming endpoint, US가 아닌 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`으로 다시 로그인하세요.                |
| US가 아닌 symbol이 거부됨             | `AAPL.US` 같은 symbol을 사용하세요. CLI는 의도적으로 US 이외의 시장을 노출하지 않습니다.                                         |
| 요청 상세가 필요함                     | `--verbose`를 추가하면 요청 URL과 경과 시간이 stderr에 출력됩니다.                                                      |