# J-Quants CLI

J-Quants API V2 を利用して日本株式市場のデータを取得できる CLI ツール `jquants` の使い方を説明します。

> **Note**
>
> セットアップ・グローバルオプション・代表的な使い方を中心に解説しています。サブコマンドのオプション一覧は `jquants <グループ> <サブコマンド> --help` で確認できます。

## 前提条件

- **アカウント登録:** J-Quants API V2 を利用するには[アカウント登録](https://jpx-jquants.com/register)が必要です。
- **プラン選択:** データ取得には Free / Light / Standard / Premium のいずれかのプランを選択してください。なお、プランによってアクセスできるエンドポイントが異なりますので、ご注意ください。

## インストール

### Homebrew（macOS / Linux）

```bash
brew install J-Quants/tap/jquants
```

### GitHub Releases

[Releases ページ](https://github.com/J-Quants/jquants-cli/releases)から各プラットフォーム向けのビルド済みバイナリをダウンロードし、`PATH` の通ったディレクトリに配置してください。

| OS      | アーキテクチャ               | ファイル                                                  |
| ------- | --------------------- | ----------------------------------------------------- |
| macOS   | Intel (x86\_64)       | `jquants-{version}-x86_64-apple-darwin.tar.gz`        |
| macOS   | Apple Silicon (ARM64) | `jquants-{version}-aarch64-apple-darwin.tar.gz`       |
| Linux   | x86\_64 (musl)        | `jquants-{version}-x86_64-unknown-linux-musl.tar.gz`  |
| Linux   | ARM64 (musl)          | `jquants-{version}-aarch64-unknown-linux-musl.tar.gz` |
| Windows | x86\_64               | `jquants-{version}-x86_64-pc-windows-msvc.zip`        |

## 認証(セットアップ)

### 推奨: OAuth2 ブラウザログイン

```bash
jquants login
```

実行するとブラウザが自動で開き、J-Quants アカウントでログインすると API Key が `~/.config/jquants/credentials.json` に保存されます。以降は API Key を明示的に指定する必要はありません。

### API Key を直接指定（代替手段）

環境変数または `.env` ファイルで設定できます。

```bash {{ title: "環境変数" }}
export JQUANTS_API_KEY=your_api_key_here
```

```ini {{ title: ".env ファイル" }}
# .env ファイル（プロジェクトルートに配置）
JQUANTS_API_KEY=your_api_key_here
```

API Key は [J-Quants Dashboard](https://jpx-jquants.com/dashboard/api-keys) から取得してください。

**認証優先順位:** `~/.config/jquants/credentials.json` の api\_key → `JQUANTS_API_KEY` 環境変数 → エラー

> **Note**
>
> - `credentials.json` や `JQUANTS_API_KEY` をリポジトリにコミットしないでください。
> - `.env` ファイルは `.gitignore` に追加し、バージョン管理から除外してください。

### ログアウト

```bash
jquants logout
```

ブラウザでログインセッションをクリアし、`~/.config/jquants/credentials.json` を削除します。

## AI Agent 連携

本ツールには AI Agent（Claude Code 等）向けの Skills ファイルが同梱されています。以下のコマンドでインストールしてください。

```bash {{ title: "npx" }}
npx skills add J-Quants/j-quants-cli
```

```bash {{ title: "jquants CLI（カレントディレクトリ）" }}
# カレントディレクトリに配置
jquants skills add
```

```bash {{ title: "jquants CLI（ディレクトリ指定）" }}
# .claude/skills/j-quants-cli-usage/ が作成される
jquants skills add --dir .claude/skills
```

## 基本的な使い方

### グローバルオプションの位置

`--output`、`--save`、`--fields` はすべて**サブコマンドの前**に指定する必要があります。

```bash {{ title: "正しい書き方" }}
# ✅ 正しい
jquants --output csv eq daily --code 86970
jquants --output json --save out.json eq master
```

```bash {{ title: "誤った書き方" }}
# ❌ 誤り（サブコマンドの後ろは無効）
jquants eq daily --code 86970 --output csv
```

### 出力フォーマット

`--output`（`-o`）フラグで出力形式を選択します。

| フォーマット    | 説明                             |
| --------- | ------------------------------ |
| `table`   | テーブル形式（デフォルト）。列名は省略表記          |
| `json`    | JSON 形式。全フィールドを完全な名前で出力        |
| `csv`     | CSV 形式。パイプ時も自動で切り替わる           |
| `parquet` | Apache Parquet 形式。`--save` が必須 |

```bash
jquants eq daily --code 86970                       # テーブル表示（デフォルト）
jquants --output json eq daily --code 86970         # JSON 出力（全フィールド）
jquants --output csv eq master                      # CSV 出力
jquants --output parquet --save out.parquet eq daily --code 86970  # Parquet 保存
```

> **Note**
>
> `--output parquet` を使う場合は **`--save` が必須**です。`--save` なしで指定するとエラーになります。

### フィールド選択

`--fields`（`-f`）で取得するフィールドを絞り込めます。フィールド名は JSON / CSV のキー名（API のフィールド名）を使用します。テーブル表示の省略列名とは異なります。

```bash
# 銘柄コード・日付・調整済み終値のみ取得
jquants -f Date,Code,AdjC eq daily --code 86970

# 複数フィールドを CSV で保存
jquants --output csv --save prices.csv -f Date,Code,Open,High,Low,Close,Volume eq daily --code 86970
```

### フィールド名の確認方法

`jquants schema <endpoint>` でフィールド一覧を確認できます（例: `jquants schema eq.daily`）。\
存在しないフィールド名を `-f` に指定すると、「利用可能フィールド」がエラーメッセージに一覧表示されます。

### ファイル保存

`--save <PATH>` でファイルに保存します。`--output` と組み合わせて使用します。

```bash
jquants --output csv --save master.csv eq master
jquants --output json --save daily.json eq daily --code 86970
jquants --output parquet --save daily.parquet eq daily --code 86970
```

> **Note**
>
> `--output table`（デフォルト）は `--save` と組み合わせることができません。ファイル保存には `csv`・`json`・`parquet` のいずれかを指定してください。保存完了時は stderr に `Saved: <path>` と表示されます。

### パイプ接続時の自動 CSV 切替

stdout がパイプ先に接続されている場合（TTY 非検出）、`--output table` でも自動的に CSV 形式で出力されます。

```bash
jquants eq master | head -5
jquants eq master | awk -F, '{print $3}'
jquants eq daily --code 86970 | python3 script.py
```

## コマンドリファレンス

### eq — 株式

株価・株式銘柄一覧・投資部門別データを取得します。

| サブコマンド              | 内容                   |
| ------------------- | -------------------- |
| `master`            | 銘柄マスタ（銘柄名・市場・業種など）   |
| `daily`             | 株価四本値（日次・調整済み OHLCV） |
| `am`                | 前場四本値                |
| `minute`            | 分足 OHLCV             |
| `earnings-calendar` | 決算発表予定日              |
| `investor-types`    | 投資部門別売買状況            |
| `trades`            | 株価ティック（歩み値・バルク取得）    |

### mkt — 市場

売買内訳・信用残高・空売り・取引カレンダーなどの市場データを取得します。

| サブコマンド              | 内容                               |
| ------------------- | -------------------------------- |
| `breakdown`         | 売買内訳                             |
| `margin-alert`      | 日々公表信用取引残高                       |
| `margin-interest`   | 信用取引週末残高                         |
| `calendar`          | 取引カレンダー（営業日・休業日）                 |
| `short-ratio`       | 業種別空売り比率（フィルタは 33 業種コード `--s33`） |
| `short-sale-report` | 空売り残高報告（公表日 `--disc-date` など）    |

### fins — 財務

財務諸表・配当情報・財務サマリーを取得します。

| サブコマンド     | 内容                                            |
| ---------- | --------------------------------------------- |
| `details`  | 財務諸表（BS / PL / CF）。全フィールドは `--output json` 推奨 |
| `dividend` | 配当情報                                          |
| `summary`  | 財務サマリー                                        |

### idx — 指数

TOPIX および各種指数の日次データを取得します。

| サブコマンド        | 内容           |
| ------------- | ------------ |
| `daily-topix` | TOPIX 日次バー   |
| `daily`       | 指数コード指定の日次バー |

### deriv — デリバティブ

先物・オプションの日次データを取得します。

| サブコマンド        | 内容              |
| ------------- | --------------- |
| `futures`     | 先物四本値           |
| `options`     | オプション四本値        |
| `options-225` | 日経 225 オプション四本値 |

### bulk — バルクダウンロード

複数銘柄・長期間などを GZ 圧縮 CSV で一括取得するためのコマンドです。

| サブコマンド | 内容                      |
| ------ | ----------------------- |
| `list` | ダウンロード可能ファイル一覧          |
| `get`  | ダウンロード URL の表示またはファイル取得 |

## シェル補完の設定

`jquants completions` でシェル補完スクリプトを生成できます。

```bash {{ title: "Bash" }}
jquants completions bash > ~/.config/bash/completions/jquants.bash
# ~/.bashrc に追記
source ~/.config/bash/completions/jquants.bash
```

```bash {{ title: "Zsh" }}
mkdir -p ~/.zfunc
jquants completions zsh > ~/.zfunc/_jquants
# ~/.zshrc に追記
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
```

```bash {{ title: "Fish" }}
jquants completions fish > ~/.config/fish/completions/jquants.fish
```

```powershell {{ title: "PowerShell" }}
jquants completions powershell | Out-File -FilePath $PROFILE -Append
```

## よくある間違いと対処法

| 間違い                                              | 正しい書き方                                                                       | 理由                                            |
| ------------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------- |
| `jquants eq daily --code 86970 --output csv`     | `jquants --output csv eq daily --code 86970`                                 | `--output` はサブコマンドの前に置く                       |
| `jquants --save out.csv eq daily --code 86970`   | `jquants --output csv --save out.csv eq daily --code 86970`                  | `--save` には `--output csv` または `json` が必要     |
| `jquants --output table --save out.txt eq daily` | `jquants --output csv --save out.csv eq daily`                               | `--output table` は `--save` と組み合わせ不可          |
| `jquants --output parquet eq daily --code 86970` | `jquants --output parquet --save out.parquet eq daily --code 86970`          | Parquet は `--save` が必須                        |
| `jquants fins details --code 86970` でデータが省略される   | `jquants --output json fins details --code 86970`                            | FS フィールドはテーブルでは「N items」と省略される。全データは JSON で取得 |
| 全銘柄ループで `eq daily --code X` を繰り返す                | `jquants bulk get --endpoint /equities/bars/daily --date YYYY-MM --download` | 大量データはバルクダウンロードを使用                            |
| バルクの GZ ファイルをそのまま読もうとする                          | ダウンロード後に `gunzip *.gz` で解凍                                                   | バルクファイルは GZ 圧縮されている                           |
| `jquants login` を実行せずに API コマンドを実行               | 最初に `jquants login` を実行する                                                    | 認証情報がないと API エラーになる                           |