0xrsydn/idx-cli
1
mirror of https://github.com/0xrsydn/idx-cli.git synced 2026-11-07 01:35:36 +00:00
Code Issues Projects Releases 1 Packages Wiki Activity
idx-cli/README.md
hermes 22b6dabaeb feat(cli): agent-native output, stdin symbols, and exit-code classes 
Phase 1 of docs/DESIGN.md:

- Output format resolves -o > IDX_OUTPUT > general.output > auto; auto
  is a table on a terminal and JSON when stdout is piped or captured.
  `config init` now writes output = "auto".
- JSON is pretty only on a terminal and compact otherwise. New `-o
  jsonl` prints one array item per line with the same key order.
- No ANSI color when stdout is not a terminal (direct owo-colors calls
  now go through output::style).
- `stocks quote -` and `stocks compare -` read symbols from stdin.
- Exit codes by class: 2 invalid input/config, 3 not found or cache
  miss, 4 upstream unavailable, 5 unsupported, 1 other.

Golden changes are limited to those documented kinds and were verified
mechanically: JSON goldens are semantically identical, tables differ
only by removed ANSI codes and the column padding comfy-table had
reserved for them (cell contents identical), exit codes match each
error's class, and help/completions only gain the new --output values.
17 new golden cases cover auto, jsonl, stdin, and the new errors.

tests/cli.rs now pins IDX_OUTPUT=table in its harness (its tests assert
table text and run piped) and parses discover JSON instead of matching
pretty-printed whitespace.

Live A/B against main: 16/16 stocks cases identical; ownership discover
got IDX 403 on both binaries, now exiting 4 instead of 1 as intended.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 08:52:13 +00:00

6.8 KiB
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)

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

  • 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 low-pe | 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.

Documentation

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