idx-cli

# idx-cli CLI tool for Indonesian stock market (IDX) analysis, built in Rust for humans and AI agents. ## Installation ### Install script (Linux, macOS) ```bash 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](docs/INSTALL.md). ### npm / npx ```bash 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](docs/NPM_DISTRIBUTION.md). Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64. On Windows, use WSL. ### Nix ```bash 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 ```bash 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](https://github.com/lexiforest/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 ```bash # 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](https://www.idx.co.id/id/perusahaan-tercatat/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](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: ```bash 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: ```bash 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 User docs, MCP setup per agent, and agent-readable `llms.txt`: **https://idx.rasyidanaf.com**. Maintainer docs: - [docs/INSTALL.md](docs/INSTALL.md): install script options - [docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md): npm package and release flow - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): providers, ownership ingest, and discovery - [docs/OWNERSHIP_SYNC.md](docs/OWNERSHIP_SYNC.md): snapshot manifest and sync rules - [docs/OWNERSHIP_PUBLISH.md](docs/OWNERSHIP_PUBLISH.md): maintainer snapshot publishing - [docs/SMOKE.md](docs/SMOKE.md): test layout and the live provider drift check - [ROADMAP.md](ROADMAP.md): planned work ## Development The canonical local and CI verification command is: ```bash 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: ```bash 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](docs/SMOKE.md). The npm wrapper has its own harness, `scripts/npm-smoke.sh`. ## License MIT