# J-Quants CLI

A guide to using the CLI tool `jquants` for retrieving Japanese stock market data via J-Quants API V2.

> **Note**
>
> This guide focuses on setup, global options, and common usage patterns. For a full list of subcommand options, run `jquants <group> <subcommand> --help`.

## Prerequisites

- **Account Registration:** An [account registration](https://jpx-jquants.com/register) is required to use J-Quants API V2.
- **Plan Selection:** Choose one of the following plans to access data: Free, Light, Standard, or Premium. Note that accessible endpoints vary by plan.

## Installation

### Homebrew (macOS / Linux)

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

### GitHub Releases

Download the pre-built binary for your platform from the [Releases page](https://github.com/J-Quants/jquants-cli/releases) and place it in a directory on your `PATH`.

| OS      | Architecture          | File                                                  |
| ------- | --------------------- | ----------------------------------------------------- |
| 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`        |

## Authentication

### Recommended: OAuth2 Browser Login

```bash
jquants login
```

Running this command automatically opens a browser. After logging in with your J-Quants account, the API Key is saved to `~/.config/jquants/credentials.json`. You do not need to specify the API Key explicitly after this step.

### Direct API Key (Alternative)

You can configure the API Key via an environment variable or a `.env` file.

```bash {{ title: "Environment Variable" }}
export JQUANTS_API_KEY=your_api_key_here
```

```ini {{ title: ".env File" }}
# .env file (place at project root)
JQUANTS_API_KEY=your_api_key_here
```

Obtain your API Key from the [J-Quants Dashboard](https://jpx-jquants.com/dashboard/api-keys).

**Authentication priority:** `api_key` in `~/.config/jquants/credentials.json` → `JQUANTS_API_KEY` environment variable → error

> **Note**
>
> - Do not commit `credentials.json` or `JQUANTS_API_KEY` to your repository.
> - Add the `.env` file to `.gitignore` to exclude it from version control.

### Logout

```bash
jquants logout
```

Clears the browser login session and removes `~/.config/jquants/credentials.json`.

## AI Agent Integration

This tool includes a Skills file for AI Agents (e.g., Claude Code). Install it with one of the following commands.

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

```bash {{ title: "jquants CLI (current directory)" }}
# Place in current directory
jquants skills add
```

```bash {{ title: "jquants CLI (specify directory)" }}
# Creates .claude/skills/j-quants-cli-usage/
jquants skills add --dir .claude/skills
```

## Basic Usage

### Global Option Placement

`--output`, `--save`, and `--fields` must all be specified **before the subcommand**.

```bash {{ title: "Correct" }}
# ✅ Correct
jquants --output csv eq daily --code 86970
jquants --output json --save out.json eq master
```

```bash {{ title: "Incorrect" }}
# ❌ Incorrect (after subcommand has no effect)
jquants eq daily --code 86970 --output csv
```

### Output Format

Use the `--output` (`-o`) flag to select the output format.

| Format    | Description                                           |
| --------- | ----------------------------------------------------- |
| `table`   | Table format (default). Column names are abbreviated. |
| `json`    | JSON format. All fields output with full names.       |
| `csv`     | CSV format. Also switches automatically when piping.  |
| `parquet` | Apache Parquet format. Requires `--save`.             |

```bash
jquants eq daily --code 86970                       # Table display (default)
jquants --output json eq daily --code 86970         # JSON output (all fields)
jquants --output csv eq master                      # CSV output
jquants --output parquet --save out.parquet eq daily --code 86970  # Save as Parquet
```

> **Note**
>
> When using `--output parquet`, **`--save` is required**. Omitting `--save` will result in an error.

### Field Selection

Use `--fields` (`-f`) to narrow down the fields to retrieve. Field names use the JSON/CSV key names (API field names), which differ from the abbreviated column names in table display.

```bash
# Retrieve only issue code, date, and adjusted close price
jquants -f Date,Code,AdjC eq daily --code 86970

# Save multiple fields as CSV
jquants --output csv --save prices.csv -f Date,Code,Open,High,Low,Close,Volume eq daily --code 86970
```

### How to Check Field Names

Use `jquants schema <endpoint>` to view the list of available fields (e.g., `jquants schema eq.daily`).
If you specify a field name that does not exist with `-f`, an error message will list the available fields.

### Saving to File

Use `--save <PATH>` to save output to a file. Combine with `--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` (default) cannot be combined with `--save`. Specify `csv`, `json`, or `parquet` for file output. A `Saved: <path>` message is printed to stderr upon completion.

### Automatic CSV Switch When Piping

When stdout is connected to a pipe (non-TTY detected), output is automatically switched to CSV format even with `--output table`.

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

## Command Reference

### eq — Equities

Retrieves stock prices, listed issue information, and investor trading data.

| Subcommand          | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `master`            | Listed issue information (name, market, sector, etc.) |
| `daily`             | Daily stock prices (OHLCV, adjusted)                  |
| `am`                | Morning session OHLCV                                 |
| `minute`            | Minute-by-minute OHLCV                                |
| `earnings-calendar` | Scheduled earnings announcement dates                 |
| `investor-types`    | Trading by investor type                              |
| `trades`            | Tick data (trade-by-trade, bulk retrieval)            |

### mkt — Market

Retrieves market data including trading breakdown, margin trading, short selling, and trading calendar.

| Subcommand          | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `breakdown`         | Trading breakdown                                                  |
| `margin-alert`      | Daily disclosed margin trading balance                             |
| `margin-interest`   | Weekly margin trading balance                                      |
| `calendar`          | Trading calendar (business days and holidays)                      |
| `short-ratio`       | Short selling ratio by sector (filter by 33-sector code `--s33`)   |
| `short-sale-report` | Short sale balance report (by disclosure date `--disc-date`, etc.) |

### fins — Financials

Retrieves financial statements, dividend information, and financial summaries.

| Subcommand | Description                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `details`  | Financial statements (BS / PL / CF). Use `--output json` for all fields. |
| `dividend` | Dividend information                                                     |
| `summary`  | Financial summary                                                        |

### idx — Indices

Retrieves daily data for TOPIX and other indices.

| Subcommand    | Description              |
| ------------- | ------------------------ |
| `daily-topix` | TOPIX daily bars         |
| `daily`       | Daily bars by index code |

### deriv — Derivatives

Retrieves daily data for futures and options.

| Subcommand    | Description              |
| ------------- | ------------------------ |
| `futures`     | Futures OHLCV            |
| `options`     | Options OHLCV            |
| `options-225` | Nikkei 225 options OHLCV |

### bulk — Bulk Download

Downloads data for multiple issues or long date ranges as GZ-compressed CSV files.

| Subcommand | Description                             |
| ---------- | --------------------------------------- |
| `list`     | List of available files for download    |
| `get`      | Display download URLs or retrieve files |

## Shell Completion

Use `jquants completions` to generate shell completion scripts.

```bash {{ title: "Bash" }}
jquants completions bash > ~/.config/bash/completions/jquants.bash
# Add to ~/.bashrc
source ~/.config/bash/completions/jquants.bash
```

```bash {{ title: "Zsh" }}
mkdir -p ~/.zfunc
jquants completions zsh > ~/.zfunc/_jquants
# Add to ~/.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
```

## Common Mistakes and Solutions

| Mistake                                                         | Correct Usage                                                                | Reason                                                                                            |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `jquants eq daily --code 86970 --output csv`                    | `jquants --output csv eq daily --code 86970`                                 | `--output` must come before the subcommand                                                        |
| `jquants --save out.csv eq daily --code 86970`                  | `jquants --output csv --save out.csv eq daily --code 86970`                  | `--save` requires `--output csv` or `json`                                                        |
| `jquants --output table --save out.txt eq daily`                | `jquants --output csv --save out.csv eq daily`                               | `--output table` cannot be combined with `--save`                                                 |
| `jquants --output parquet eq daily --code 86970`                | `jquants --output parquet --save out.parquet eq daily --code 86970`          | Parquet requires `--save`                                                                         |
| Data appears truncated with `jquants fins details --code 86970` | `jquants --output json fins details --code 86970`                            | Financial statement fields are abbreviated as 'N items' in table format; use JSON to get all data |
| Looping `eq daily --code X` for all issues                      | `jquants bulk get --endpoint /equities/bars/daily --date YYYY-MM --download` | Use bulk download for large data sets                                                             |
| Trying to read GZ bulk files directly                           | Decompress after download with `gunzip *.gz`                                 | Bulk files are GZ-compressed                                                                      |
| Running API commands without `jquants login` first              | Run `jquants login` first                                                    | Missing credentials will result in an API error                                                   |