mirror of
https://github.com/0xrsydn/idx-cli.git
synced 2026-11-07 09:45:36 +00:00
docs: refresh README for v0.2.4
- Install: add npm/npx (with the pnpm/bun opt-in), platform coverage, pin example v0.2.4; Cargo builds from source. - Runtime helpers as a table, corrected: curl-impersonate is needed for IDX ownership discover/import and Yahoo fundamentals (IDX_PROVIDER=yahoo), not for stocks history; mutool only for legacy PDF reports. Everyday use needs neither. - Quick start and Features now cover ownership (sync, ticker, entity, search, changes, concentration, cross-holders, graph; XLSX source on the IDX Data Kepemilikan Saham page) and the full stocks command set and providers. Every example was run against v0.2.4. - Documentation index; script test suites. - docs: example versions -> v0.2.4; npm publish needs 2FA and a fresh version number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017a5Cv5Z1NzdYKgKnTiAF4E
This commit is contained in:
hermes
parent
b88425f310
commit
3299093e18
3 changed files with 96 additions and 23 deletions
108
README.md
108
README.md
|
|
@ -13,22 +13,23 @@ curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | s
|
|||
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.3 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md).
|
||||
`sh -s -- --version v0.2.4 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md).
|
||||
|
||||
### Cargo
|
||||
### npm / npx
|
||||
|
||||
```bash
|
||||
cargo install idx-cli
|
||||
npx idx-cli --help # run without installing
|
||||
npm install --global idx-cli
|
||||
```
|
||||
|
||||
This installs the `idx` binary. `idx-cli` currently requires Rust `1.85+`.
|
||||
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).
|
||||
|
||||
If you use the install script or the Cargo install path directly, some commands also require helper tools at runtime:
|
||||
|
||||
- Yahoo-authenticated flows require a `curl_chrome*` binary from `curl-impersonate-chrome` in `PATH`, or `IDX_CURL_IMPERSONATE_BIN` pointing at that binary.
|
||||
- Ownership PDF import requires `mutool` from MuPDF in `PATH`.
|
||||
|
||||
Install those helpers with your OS package manager, or use the Nix app/package below so they are wrapped automatically.
|
||||
Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64.
|
||||
On Windows, use WSL.
|
||||
|
||||
### Nix
|
||||
|
||||
|
|
@ -37,26 +38,81 @@ nix run github:0xrsydn/idx-cli -- version
|
|||
nix profile install github:0xrsydn/idx-cli#default
|
||||
```
|
||||
|
||||
The Nix app wraps `idx` with `curl-impersonate` and `mupdf`, so the Yahoo auth and ownership PDF helper tools are available automatically.
|
||||
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.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*` / `curl_firefox*` from [curl-impersonate](https://github.com/lexiforest/curl-impersonate) (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 -o json stocks quote BBCA
|
||||
idx stocks history BBCA --period 3mo
|
||||
idx config init
|
||||
idx cache info
|
||||
idx --offline stocks quote BBCA
|
||||
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
|
||||
|
||||
- Provider abstraction (swap data sources behind one interface)
|
||||
- Local file cache with TTL
|
||||
- Offline mode with stale-cache fallback
|
||||
- Human table output and machine-friendly JSON output
|
||||
### 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 `screen`er
|
||||
- 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
|
||||
|
||||
- Human-readable tables on stdout, JSON with `-o json`, errors on stderr
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
@ -81,6 +137,17 @@ Precedence order:
|
|||
|
||||
- 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](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) and
|
||||
[docs/OWNERSHIP_SELF_HOSTED.md](docs/OWNERSHIP_SELF_HOSTED.md): maintainer snapshot publishing
|
||||
- [docs/SMOKE.md](docs/SMOKE.md): smoke tests against live providers
|
||||
|
||||
## Development
|
||||
|
||||
|
|
@ -94,6 +161,9 @@ Prek hooks are configured for quality gates:
|
|||
- pre-commit: `cargo fmt --check` + `cargo clippy -- -D warnings`
|
||||
- pre-push: `cargo test`
|
||||
|
||||
Script test suites (no live network): `scripts/install-sh-test.sh`,
|
||||
`scripts/publish-ownership-snapshot-test.sh`, and `scripts/npm-smoke.sh`.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ them yourself.
|
|||
Pass flags through the pipe with `sh -s --`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.3 --dir ~/bin
|
||||
curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.4 --dir ~/bin
|
||||
```
|
||||
|
||||
## Supported platforms
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ npx idx-cli --help
|
|||
```
|
||||
|
||||
The package version and the release tag must match. For example, package
|
||||
version `0.2.3` downloads assets from the `v0.2.3` GitHub Release.
|
||||
version `0.2.4` downloads assets from the `v0.2.4` GitHub Release.
|
||||
|
||||
The postinstall script downloads `SHA256SUMS` from the same release and
|
||||
refuses to install a binary whose checksum does not match.
|
||||
|
|
@ -81,7 +81,7 @@ URLs must stay aligned with `scripts/install.js`.
|
|||
To attach binaries to a tag that already exists, run the workflow manually:
|
||||
|
||||
```bash
|
||||
gh workflow run release.yml -f tag=v0.2.3
|
||||
gh workflow run release.yml -f tag=v0.2.4
|
||||
```
|
||||
|
||||
Pull requests that touch the workflow or the installer run the build jobs
|
||||
|
|
@ -91,4 +91,7 @@ Release order:
|
|||
|
||||
1. Push the tag, or run the workflow for an existing tag.
|
||||
2. Confirm the release has all binaries plus `SHA256SUMS`.
|
||||
3. Run `npm publish`.
|
||||
3. Run `npm publish` from the tagged commit. The account has two-factor auth,
|
||||
so npm asks for a browser approval or `--otp=<code>`. A version number
|
||||
can never be republished, so bump `Cargo.toml` and `package.json` together
|
||||
before tagging.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue