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)

```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.5.0 --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`, or on first run when the package manager skips install scripts
(npm 12 under `npx`, pnpm 10+, bun). 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 stocks intraday BBCA          # today by the minute (Stockbit, delayed)
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 `--provider`/`IDX_PROVIDER=msn|yahoo|stockbit`
  and `IDX_HISTORY_PROVIDER=auto|yahoo|msn|stockbit`
- Stockbit, opt-in: without a login, `stocks intraday` (today's price by the
  minute) and `--provider stockbit` quotes with the best bid/offer while the
  market is open, delayed at least 10 minutes. With your own account
  (`idx stockbit login`): `stocks orderbook` depth, live
  quotes, Stockbit daily history, and corporate actions (`stocks actions`,
  `stocks calendar`: dividends, rights, splits, meetings, IPOs and more), and
  insider and major holder buys and sells (`ownership movements`). Personal use under Stockbit's terms; see
  the [Stockbit page](https://idx.rasyidanaf.com/cli/stockbit/)
- 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 21 tools:
`get_quotes`, `get_intraday`, `get_orderbook`, `get_corporate_actions`,
`get_corporate_calendar`, `get_shareholder_movements`, `stockbit_status`, `stockbit_login`, `get_price_history`, `screen_stocks`, `get_company`,
`analyze_stock`, `compare_stocks`, `get_broker_summary`, `analyze_bandar`,
`get_foreign_flow`, `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