J-Quants CLI

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

Prerequisites

• Account Registration: An account registration 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)

brew install J-Quants/tap/jquants

GitHub Releases

Download the pre-built binary for your platform from the Releases page and place it in a directory on your PATH.

Authentication

Recommended: OAuth2 Browser Login

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.

export JQUANTS_API_KEY=your_api_key_here

Obtain your API Key from the J-Quants Dashboard.

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

Logout

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.

npx skills add J-Quants/jquants-cli

Basic Usage

Global Option Placement

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

# ✅ Correct
jquants --output csv eq daily --code 86970
jquants --output json --save out.json eq master

Output Format

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

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

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.

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

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

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.

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.

mkt — Market

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

edinet — EDINET Documents

Retrieves data derived from EDINET filings such as annual securities reports and large volume holding reports. Requires the Standard plan or higher.

fins — Financials

Retrieves financial statements, dividend information, earnings announcement dates, and financial summaries.

idx — Indices

Retrieves daily data for TOPIX and other indices.

deriv — Derivatives

Retrieves daily data for futures and options.

td — TDnet Timely Disclosure

Retrieves TDnet timely disclosure index, disclosure files, and bulk data. Requires a TDnet add-on subscription.

bulk — Bulk Download

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

Shell Completion

Use jquants completions to generate shell completion scripts.

jquants completions bash > ~/.config/bash/completions/jquants.bash
# Add to ~/.bashrc
source ~/.config/bash/completions/jquants.bash

Common Mistakes and Solutions