0xrsydn/idx-cli
1
mirror of https://github.com/0xrsydn/idx-cli.git synced 2026-11-07 09:45:36 +00:00
Code Issues Projects Releases 1 Packages Wiki Activity
idx-cli/README.md
0xrsydn ae0ca0c109 feat: shareholder movements from the Stockbit session (ownership movements) 
`idx ownership movements [SYMBOL]` and the MCP tool
`get_shareholder_movements` list reported changes in insiders' and major
holders' stakes, newest first, from Stockbit's
/insider/company/majorholder: IDX insider disclosures (any size, with the
trade price) and KSEI changes of holders at 5% and above (Stockbit's
estimated price). Stockbit filters by date range, holder id, action and
source; each page is 50 rows and one request, up to 10 pages, cached an
hour per page under every filter.

Rows keep exact signed share counts and the stake in basis points as
Stockbit rounds it; unknown action labels are kept as `other` rather than
dropped. JSON is {movements, more}; JSONL is one movement per line. The
command lives under `ownership` but needs no import, and `ownership`
commands now take --offline / --no-cache for it.

The per-symbol summary score is the next PR; docs/STOCKBIT.md records the
endpoint's parameters and action types as checked on 2026-11-03.

Claude-Session: https://claude.ai/code/session_01RqPPVeVDrnLoP7NUZmLRxY
2026-11-03 16:02:26 +07:00

237 lines
8.7 KiB
Markdown
Raw Blame History

# 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.4.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
Reference in a new issue View git blame Copy permalink