idx-cli/README.md

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.2.4 --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.85+.

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

• Human-readable tables on stdout, JSON with -o json, errors on stderr

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

Agent-friendly usage

• Use idx --help and subcommand help for discoverability
• Use -o json / --output json for structured output
• idx completions <shell> generates shell completions

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: smoke tests against live providers
• ROADMAP.md: planned work

Development

The canonical local and CI verification command is:

nix flake check -L

It covers Rust formatting, Clippy, tests, crate package verification, release builds, offline CLI smoke, publisher regressions, installer tests with sh and dash, and ShellCheck for installer/smoke scripts. 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 for portability. Live-provider smoke remains opt-in; see docs/SMOKE.md for check selection and caching details. The npm distribution harness remains available separately as scripts/npm-smoke.sh.

License

MIT