idx-cli

CLI tool for Indonesian stock market (IDX) analysis, built in Rust for humans and AI agents.

Installation

Install script (Linux, macOS)

curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh

Downloads the prebuilt idx binary for your platform from GitHub Releases, verifies it against the release SHA256SUMS, and installs it into ~/.local/bin without sudo. Pin a version or change the directory with sh -s -- --version v0.3.1 --dir ~/bin. See docs/INSTALL.md.

npm / npx

npx idx-cli --help          # run without installing
npm install --global idx-cli

The npm package downloads the same checksum-verified release binary during postinstall. pnpm 10+ and bun skip install scripts by default; allow them with pnpm add --global --allow-build=idx-cli idx-cli or bun add --global --trust idx-cli. See docs/NPM_DISTRIBUTION.md.

Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64. On Windows, use WSL.

Nix

nix run github:0xrsydn/idx-cli -- version
nix profile install github:0xrsydn/idx-cli#default

The Nix package wraps idx with curl-impersonate and mupdf, so every helper tool below is available automatically.

Cargo

cargo install idx-cli

Builds from source; requires Rust 1.89+.

Runtime helper tools

The install script, npm, and Cargo installs ship only the idx binary. A few commands call external tools:

Tool	Needed for
curl_chrome* from curl-impersonate (ownership also tries its Firefox and Safari profiles), or IDX_CURL_IMPERSONATE_BIN	ownership discover / import --url from IDX (behind Cloudflare), and Yahoo fundamentals when IDX_PROVIDER=yahoo
mutool from MuPDF	importing legacy PDF ownership reports only

Everyday use (stocks with the default MSN provider, including history, ownership sync, and every local ownership query) needs neither.

Quick start

# Stocks
idx stocks quote BBCA
idx stocks quote BBCA,BBRI,BMRI
idx stocks history BBCA --period 3mo
idx stocks technical BBCA
idx stocks fundamental BBCA
idx stocks compare BBCA BBRI BMRI
idx -o json stocks quote BBCA

# Ownership: download the maintained snapshot once, then query locally
idx ownership sync
idx ownership ticker BBCA
idx ownership entity "ANTHONI SALIM"
idx ownership search salim
idx ownership changes --from 2026-07-31 --to 2026-08-31

Features

Stocks

• Quotes, OHLC history, company profile, financial statements, earnings, news, crowd sentiment, and AI insights
• Analysis: technical, growth, valuation, risk, and a combined fundamental report; multi-symbol compare; MSN stock screen
• Providers: MSN is the default for quotes, fundamentals, and screening; Yahoo serves history. Switch with IDX_PROVIDER=msn|yahoo and IDX_HISTORY_PROVIDER=auto|yahoo|msn
• Local file cache with TTL, and --offline mode with stale-cache fallback

Ownership (KSEI shareholders above 1%)

• Source: the monthly KSEI holder register ("Pemegang Saham di Atas 1%") published by IDX. Since June 2026 it is an XLSX file on IDX's Data Kepemilikan Saham page; earlier months were PDF announcements
• ownership sync installs a maintained SQLite snapshot (checked daily, currently the latest three months), after which every query runs offline
• Queries: holders per ticker, holdings per entity, entity search, month-over-month changes, concentration, cross-holders, and an ownership graph
• Self-serve ingest: ownership discover finds the latest reports, and ownership import --url <xlsx-or-pdf> / --file loads them into your local database. See docs/OWNERSHIP_SYNC.md

Output

• Tables when you run idx in a terminal; compact JSON when its output is piped or captured, so scripts and AI agents get structured data with no flag
• -o table|json|jsonl (or IDX_OUTPUT, or general.output in the config) overrides that; jsonl prints one array item per line
• Errors go to stderr, as one JSON object in JSON modes

Configuration

Config file location:

• ~/.config/idx/config.toml

You can configure using:

• Config file (idx config init, idx config set)
• Environment variables
• CLI flags

Precedence order:

1. CLI flags
2. Environment variables
3. Config file
4. Built-in defaults

Scripting and agents

idx composes with jq, Python, and other shell tools:

idx stocks quote BBCA BBRI | jq -r '.[] | "\(.symbol) \(.price)"'
idx -o jsonl stocks history BBCA --period 1y | tail -5
idx stocks screen --filter high-dividend | jq -r '.[].symbol' | idx stocks compare -

• stdout carries only data; warnings and errors go to stderr
• - reads symbols from stdin for stocks quote and stocks compare
• No color codes when output is not a terminal
• Exit codes: 0 success, 2 invalid input or config, 3 not found or no cached data, 4 upstream unavailable (retry later), 5 unsupported, 1 other
• idx completions <shell> generates shell completions

If you ran idx config init before v0.3, your config pins output = "table"; change it to auto with idx config set general.output auto.

MCP server

idx-mcp serves the same data to MCP clients over stdio, as 11 tools: get_quotes, get_price_history, screen_stocks, get_company, analyze_stock, compare_stocks, get_shareholders, get_investor_holdings, search_investors, get_ownership_changes, and ownership_status. Live results come wrapped as {data, source, fetched_at, stale}; errors use the CLI's {error, code, message} body. It shares idx's config, cache, and ownership database.

Install it like idx (npm, Cargo, or Nix), then register it with your MCP client:

claude mcp add idx -- npx -y idx-mcp   # Claude Code, via npm
cargo install idx-mcp                  # or build it (Rust 1.89+)
nix profile install github:0xrsydn/idx-cli#idx-mcp

Other clients run the idx-mcp command over stdio.

Ownership tools need a populated database: run idx ownership sync once, or start the server with idx-mcp --allow-sync to expose an ownership_sync tool (it downloads several MB).

Documentation

• docs/INSTALL.md: install script options
• docs/NPM_DISTRIBUTION.md: npm package and release flow
• docs/ARCHITECTURE.md: providers, ownership ingest, and discovery
• docs/OWNERSHIP_SYNC.md: snapshot manifest and sync rules
• docs/OWNERSHIP_PUBLISH.md: maintainer snapshot publishing
• docs/SMOKE.md: test layout and the live provider drift check
• ROADMAP.md: planned work

Development

The canonical local and CI verification command is:

nix flake check -L

It covers Rust formatting, Clippy, unit and CLI integration tests, crate package verification, the packaged binary, publisher regressions, installer tests with sh and dash, and ShellCheck. The checks use pinned tools and cached Nix outputs; an unchanged successful check is reused rather than rerun.

For a focused edit/debug loop, use the same pinned toolchain:

nix develop --command cargo test full_screener

Configured Prek hooks keep whitespace/conflict checks at pre-commit and run nix flake check -L at pre-push. There is no separate full Cargo test/lint gate to repeat after a successful flake check.

CI additionally checks the installer with native macOS tools. The live provider drift check (scripts/live-smoke.sh) is opt-in; see docs/SMOKE.md. The npm wrapper has its own harness, scripts/npm-smoke.sh.

License

MIT