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

feat(web): idx website and user docs (Astro Starlight)

Browse source 
Landing page plus docs for install, quickstart, config, the stocks and
ownership CLI, output and exit codes, the MCP server and per-agent setup,
agent usage, and an agent-led install page (agents/install.md) that a
coding agent follows from a one-line prompt.

- Every docs page is also served as Markdown at <path>.md; llms.txt and
  llms-full.txt come from starlight-llms-txt; a SKILL.md for skill-based
  harnesses is under /skills/idx/.
- The CLI reference and MCP tools pages are generated from idx --help and
  the tools golden; a new web-generated flake check fails when they drift.
- nix develop .#web provides bun; Cloudflare Pages builds web/ on pushes.
- Package homepage metadata points at https://idx.rasyidanaf.com.
- .cloudflare/ (the cf CLI's account cache) is git-ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
hermes 2026-10-15 05:12:45 +00:00
commit e6805474f5
37 changed files with 3629 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

33
web/src/content/docs/about.md Normal file
View file

@ -0,0 +1,33 @@
---
title: About the data
description: Where idx's data comes from, how fresh it is, and the project's terms.
---
## Sources
| Data | Source | Freshness |
| --- | --- | --- |
| Quotes, company data, screening | MSN Money (default) or Yahoo Finance | live, cached for 5 minutes (quotes) or 1 hour (fundamentals) |
| Price history | Yahoo Finance (default) or MSN | live |
| Ownership | the KSEI register of holders above 1% ("Pemegang Saham di Atas 1%"), published monthly by IDX | the maintained snapshot is checked daily and rebuilt when IDX publishes a new month |
Quotes from these providers can be delayed. The ownership register lists
only holders above 1%; everything below is reported as free float.
## The ownership snapshot
`idx ownership sync` downloads a SQLite snapshot built from IDX's published
reports and attached to the
[GitHub release `ownership-snapshot-current`](https://github.com/0xrsydn/idx-cli/releases/tag/ownership-snapshot-current),
with a manifest and SHA-256 checksum. You can build the same database
yourself from IDX's files with `idx ownership import`.
## Terms
idx is open source under the MIT license:
[github.com/0xrsydn/idx-cli](https://github.com/0xrsydn/idx-cli).
It is not affiliated with, endorsed by, or connected to PT Bursa Efek
Indonesia (IDX), PT Kustodian Sentral Efek Indonesia (KSEI), Microsoft or
Yahoo. Data is provided as is, without warranty. Nothing here is investment
advice.

60
web/src/content/docs/agents/index.md Normal file
View file

@ -0,0 +1,60 @@
---
title: Using idx from an agent
description: How an AI agent should call idx, through MCP or the CLI.
---
An agent can reach idx two ways:
- **MCP** ([setup](/mcp/setup/)): typed tools with input schemas, the best
fit for chat-style agents.
- **The CLI**: for agents that run shell commands. No setup beyond
installing `idx`; output is JSON automatically when captured.
## Using the CLI
What an agent needs to know:
- Output is JSON whenever stdout is not a terminal, so capture it and parse
it; no flag is needed. Use `-o jsonl` for long lists.
- On failure stdout is empty and stderr holds one JSON object,
`{"error": true, "code": "...", "message": "..."}`.
- Exit codes say what to do next: `2` fix the input, `3` not found (or no
cached data offline), `4` provider unavailable, retry later, `5`
unsupported, `1` other.
- Tickers are IDX codes (`BBCA`); `.JK` is optional. Several tickers can be
passed at once to `stocks quote` and `stocks compare`.
- Ownership queries need `idx ownership sync` once; after that they run
offline. `idx -o json ownership releases` shows which months exist.
## Recipes
```bash
# price and day change for several stocks
idx stocks quote BBCA BBRI BMRI | jq '.[] | {symbol, price, change_pct}'
# largest holders and concentration
idx ownership ticker BBCA | jq '{holders: [.holders[] | {name, pct: (.percentage_bps / 100)}], concentration}'
# what one investor holds
idx ownership entity "ANTHONI SALIM"
# holder changes between the two latest months
idx -o json ownership releases | jq -r '.[0:2][].as_of_date'
idx ownership changes --from 2026-08-31 --to 2026-09-30
```
Percentages in ownership output are basis points (`5494` = 54.94%).
## Skill file
For harnesses that load skills (Claude Code, pi, opencode, and others),
[`SKILL.md`](/skills/idx/SKILL.md) packages these rules so the agent uses the
CLI correctly without MCP. Save it as `idx/SKILL.md` in your harness's skills
directory, for example `~/.claude/skills/idx/SKILL.md`.
## Machine-readable docs
- [`/llms.txt`](/llms.txt): an index of these docs for language models.
- [`/llms-full.txt`](/llms-full.txt): every page in one file.
- Any page as Markdown: add `.md` to its path, for example
[`/agents/install.md`](/agents/install.md).

95
web/src/content/docs/agents/install.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Agent-led install
description: Instructions for a coding agent to install idx and register idx-mcp with itself.
---
This page is written for a coding agent. A user sent you here to install
**idx** (a CLI for Indonesian stock market and KSEI ownership data) and
register its MCP server, **idx-mcp**, with the agent harness you are running
in. Follow the steps in order and report back at the end.
Ground rules:
- Never use `sudo`. Install into the user's home directory.
- Before you edit a config file outside the current project (anything under
`~`), show the user the exact change and ask for confirmation.
- If a step fails, stop and tell the user what failed and the error, rather
than trying unrelated workarounds.
## 1. Check the platform
Run `uname -sm`. Supported: Linux x86_64/aarch64 and macOS x86_64/arm64. On
Windows, stop and tell the user to use WSL.
## 2. Install idx
Use the first option that applies:
1. **Node.js is available** (`node --version` succeeds): nothing to install
for the MCP server, which runs through `npx -y idx-mcp`. Install the CLI
with `npm install --global idx-cli`; if that fails with a permissions
error, skip it and use `npx -y idx-cli` in place of `idx` below.
2. **Otherwise**: run the install script, which verifies checksums and
installs to `~/.local/bin`:
```bash
curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh
```
It installs only `idx`. For the MCP server without Node.js, use
`cargo install idx-mcp` if `cargo` exists; otherwise tell the user that
idx-mcp needs Node.js, Cargo or Nix, and continue with the CLI only.
Confirm with `idx version` (or `npx -y idx-cli version`).
## 3. Register idx-mcp with yourself
Work out which harness you are, then apply its setup. Use `npx` and
`["-y", "idx-mcp"]` as command and arguments, or `idx-mcp` with no arguments
if you installed the binary.
| Harness | How |
| --- | --- |
| Claude Code | run `claude mcp add idx -- npx -y idx-mcp` |
| Codex | add to `~/.codex/config.toml`: `[mcp_servers.idx]` with `command = "npx"`, `args = ["-y", "idx-mcp"]` |
| Cursor | add to `~/.cursor/mcp.json` under `mcpServers`: `"idx": {"command": "npx", "args": ["-y", "idx-mcp"]}` |
| opencode | add to `~/.config/opencode/opencode.json` under `mcp`: `"idx": {"type": "local", "command": ["npx", "-y", "idx-mcp"], "enabled": true}` |
| pi | add to `~/.pi/agent/mcp.json` under `mcpServers`: `"idx": {"command": "npx", "args": ["-y", "idx-mcp"], "exposure": "direct"}` |
| Hermes | add to `~/.hermes/config.yaml` under `mcp_servers`: `idx` with `command: npx`, `args: ["-y", "idx-mcp"]`, `enabled: true` |
| anything else | find how your harness registers a stdio MCP server, and ask the user if unsure |
Merge into existing files; never overwrite other servers or settings. Full
examples: [MCP setup](/mcp/setup/).
## 4. Download ownership data
```bash
idx ownership sync
```
This downloads a few MB into `~/.local/share/idx/ownership.db`. It is safe to
rerun.
## 5. Verify
Run:
```bash
idx -o json ownership ticker BBCA
```
It should list holders, the first being DWIMURIA INVESTAMA ANDALAN. Most
harnesses load MCP servers at startup, so the `idx` tools usually appear only
after a restart. If yours already shows them, call `get_shareholders` with
`{"ticker": "BBCA"}` as well.
## 6. Report to the user
Tell the user, briefly:
- what you installed and how (npm, install script or Cargo), and the version;
- which config file you changed for idx-mcp, or why you didn't;
- the result of the verification (largest BBCA holder and its percentage);
- whether they need to restart the agent to use the idx tools;
- a next thing to try, such as asking "Who are BBCA's largest holders, and
what changed last month?"

53
web/src/content/docs/cli/output.md Normal file
View file

@ -0,0 +1,53 @@
---
title: Output and exit codes
description: Tables, JSON, errors and exit codes; the contract scripts and agents rely on.
---
## Formats
| `-o` | Prints |
| --- | --- |
| `auto` (default) | a table when stdout is a terminal, compact JSON otherwise |
| `table` | a table |
| `json` | one JSON document |
| `jsonl` | one JSON value per line (one per array item) |
Set the default with `IDX_OUTPUT` or `general.output`. Colour is off whenever
stdout is not a terminal, and with `--no-color`.
## The contract
- stdout carries only data; warnings, progress and errors go to stderr.
- On failure stdout is empty.
- In JSON modes an error is one JSON object on stderr:
```json
{"error":true,"code":"INVALIDINPUT","message":"invalid input: invalid ticker symbol '../x'"}
```
## Exit codes
| Exit | Meaning | What to do |
| --- | --- | --- |
| `0` | success | |
| `2` | invalid input or config | fix the command |
| `3` | not found, no data, or no cached data offline | check the ticker or name; go online |
| `4` | upstream unavailable | retry later |
| `5` | unsupported | use another command or provider |
| `1` | anything else | read the message |
## Pipes
```bash
# names and prices
idx stocks quote BBCA BBRI | jq -r '.[] | "\(.symbol) \(.price)"'
# the last five daily closes
idx -o jsonl stocks history BBCA --period 1y | tail -5
# symbols from stdin
idx stocks screen --filter high-dividend | jq -r '.[].symbol' | idx stocks compare -
```
`stocks quote` and `stocks compare` read symbols from stdin when given `-`,
separated by whitespace or commas.

57
web/src/content/docs/cli/ownership.md Normal file
View file

@ -0,0 +1,57 @@
---
title: Ownership
description: KSEI shareholder data, synced once and queried offline.
---
The ownership commands work on the monthly KSEI register of holders above 1%
("Pemegang Saham di Atas 1%") that IDX publishes for every listed company.
idx keeps it in a local SQLite database, so queries are instant and work
offline.
## Get the data
```bash
idx ownership sync
```
This downloads a maintained snapshot (a few MB, currently the latest three
months) and installs it. Run it again any time: it does nothing when you are
already current, and it never replaces a database holding more history than
the snapshot. `idx ownership releases` lists the months you have.
## Queries
```bash
idx ownership ticker BBCA # holders of one stock, with concentration
idx ownership entity "ANTHONI SALIM" # every holding of one investor
idx ownership search salim # find investor names
idx ownership changes --from 2026-08-31 --to 2026-09-30
idx ownership concentration --top 20 # most concentrated stocks (by HHI)
idx ownership cross-holders --min-tickers 3
idx ownership graph BBCA --depth 2 # ownership network; --format dot for Graphviz
```
`changes` lists holders that are new, exited, increased or decreased between
two releases. `ticker` also reports concentration: the top holder's share,
the top three, the Herfindahl index (HHI) and the free float (shares held by
holders below 1%).
## Import reports yourself
The snapshot covers most needs. To load a month it lacks, or older history,
import IDX's reports directly:
```bash
idx ownership discover # find the latest report URLs on IDX
idx ownership import --url <xlsx-or-pdf> # needs curl-impersonate
idx ownership import --file report.xlsx # or a local XLSX, PDF, ZIP or TXT
```
Since June 2026 IDX publishes the register as XLSX; earlier months were PDF
announcements, which need `mutool`. See [helper tools](/start/install/#helper-tools).
## Entity names
The register spells some investors differently from month to month.
`idx ownership resolve` lists unresolved names and lets you map an alias to
an entity or merge two entities.

1103
web/src/content/docs/cli/reference.md Normal file
View file

File diff suppressed because it is too large Load diff

67
web/src/content/docs/cli/stocks.md Normal file
View file

@ -0,0 +1,67 @@
---
title: Stocks
description: Quotes, history, company data, analysis and screening.
---
All `stocks` commands take IDX tickers (`BBCA`, or `BBCA.JK`). Every flag is
listed in the [command reference](/cli/reference/).
## Quotes and history
```bash
idx stocks quote BBCA BBRI,BMRI
idx stocks history BBCA --period 1y --interval 1wk
```
`quote` takes several tickers, separated by spaces or commas, or `-` to read
them from stdin. `history` takes `--period` (`1d` to `5y`) and `--interval`
(`1d`, `1wk`, `1mo`).
## Company data
| Command | What it shows |
| --- | --- |
| `profile` | sector, industry, description, contacts and officers |
| `financials` | income, balance sheet and cash flow statements (`--statement income,balance`) |
| `earnings` | reported and estimated earnings |
| `sentiment` | crowd sentiment |
| `insights` | AI insights from the provider |
| `news` | recent news |
## Analysis
| Command | What it computes |
| --- | --- |
| `technical` | trend, RSI, MACD, moving averages and signals |
| `growth` | revenue and earnings growth rating |
| `valuation` | P/E, P/B, ROE, net margin and EV/EBITDA, with a rating |
| `risk` | debt to equity, current ratio and ROA, with a rating |
| `fundamental` | growth, valuation and risk in one report |
| `compare` | `fundamental` for several tickers side by side |
```bash
idx stocks fundamental BBRI
idx stocks compare BBCA BBRI BMRI
```
## Screening
```bash
idx stocks screen --filter high-dividend --limit 20
```
Filters: `top-performers` (default), `worst-performers`, `high-dividend`,
`low-pe`, `52w-high`, `52w-low`, `high-volume`, `large-cap`.
Screen results pipe straight into `compare`:
```bash
idx stocks screen --filter high-dividend | jq -r '.[].symbol' | idx stocks compare -
```
## Providers
MSN is the default for quotes, company data and screening; Yahoo serves
price history. Switch with `IDX_PROVIDER=msn|yahoo` and
`IDX_HISTORY_PROVIDER=auto|yahoo|msn`, or the matching
[config keys](/start/config/).

56
web/src/content/docs/mcp/index.md Normal file
View file

@ -0,0 +1,56 @@
---
title: MCP server
description: idx-mcp serves idx's stock and ownership data to AI agents over MCP.
---
`idx-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
server over stdio. It gives an agent the same data as the `idx` CLI, as
[11 tools](/mcp/tools/): quotes, price history, screening, company data,
analysis, comparison, and the KSEI ownership queries.
It shares idx's [config, cache and ownership database](/start/config/#files-idx-keeps),
so `idx ownership sync` in a terminal also feeds the server.
[Set it up in your agent →](/mcp/setup/)
## Results
Tools that fetch live data return:
```json
{
"data": { "...": "the same shape as idx -o json" },
"source": "msn",
"fetched_at": "2026-10-15T03:20:11Z",
"stale": false
}
```
`source` is the provider (`msn` or `yahoo`). Results are cached on disk;
`stale` is true when an expired cache entry was served because a fresh fetch
failed. Ownership tools return their data directly, from the local
database.
Errors come back as a tool result with `isError` set and the CLI's error
body, so the agent can decide whether to retry:
```json
{"error": true, "code": "PROVIDERUNAVAILABLE", "message": "..."}
```
## Limits
| Input | Limit |
| --- | --- |
| tickers per call (`get_quotes`, `compare_stocks`) | 20, duplicates removed |
| `screen_stocks` `limit` | 200 |
| `search_investors` `limit` | 100 |
| `get_ownership_changes` `limit` | 2000 (default 200) |
| concurrent tool calls | 4 |
## Ownership data
Ownership tools need a populated database. Either run `idx ownership sync`
once, or start the server with `--allow-sync`, which adds an
`ownership_sync` tool so the agent can download the snapshot itself (several
MB).

142
web/src/content/docs/mcp/setup.mdx Normal file
View file

@ -0,0 +1,142 @@
---
title: Set up idx-mcp
description: Add idx-mcp to Claude Code, Codex, Cursor, opencode, pi, Hermes or any MCP client.
sidebar:
label: Setup
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
:::tip[Quickest: let your agent do it]
Paste this into your coding agent. It follows
[agents/install.md](/agents/install/): installs idx, registers idx-mcp with
itself, syncs ownership data and runs a test call. It asks before changing
global config.
```text wrap
Install idx-cli and its MCP server for me by following https://idx.rasyidanaf.com/agents/install.md, then show me that it works.
```
:::
Or set it up yourself:
## 1. Get the server
Nothing to install if your client can run `npx`: the configs below use
`npx -y idx-mcp`. Otherwise install the binary once and use `idx-mcp` as the
command:
```bash
cargo install idx-mcp # Rust 1.89+
nix profile install github:0xrsydn/idx-cli#idx-mcp
```
## 2. Add it to your client
<Tabs syncKey="agent">
<TabItem label="Claude Code">
```bash
claude mcp add idx -- npx -y idx-mcp
```
</TabItem>
<TabItem label="Codex">
`~/.codex/config.toml`:
```toml
[mcp_servers.idx]
command = "npx"
args = ["-y", "idx-mcp"]
```
</TabItem>
<TabItem label="Cursor">
`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
```json
{
"mcpServers": {
"idx": { "command": "npx", "args": ["-y", "idx-mcp"] }
}
}
```
</TabItem>
<TabItem label="opencode">
`opencode.json` in a project, or `~/.config/opencode/opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"idx": { "type": "local", "command": ["npx", "-y", "idx-mcp"], "enabled": true }
}
}
```
</TabItem>
<TabItem label="pi">
`~/.pi/agent/mcp.json`:
```json
{
"mcpServers": {
"idx": { "command": "npx", "args": ["-y", "idx-mcp"], "exposure": "direct" }
}
}
```
`"exposure": "direct"` gives the agent each tool by name.
</TabItem>
<TabItem label="Hermes">
`~/.hermes/config.yaml`:
```yaml
mcp_servers:
idx:
command: npx
args: ["-y", "idx-mcp"]
enabled: true
```
</TabItem>
<TabItem label="Other">
Any MCP client that runs stdio servers: command `npx`, arguments
`-y idx-mcp` (or the command `idx-mcp` if installed). Add `--allow-sync` to
the arguments to expose `ownership_sync`.
</TabItem>
</Tabs>
These are the setups that `tests/agents/agent-smoke.sh` drives with real
agents.
## 3. Get ownership data
Ownership tools read a local database. Fill it once:
```bash
npx -y idx-cli ownership sync # or: idx ownership sync
```
Or start the server with `--allow-sync` so the agent can call
`ownership_sync` itself.
## 4. Check it works
Ask your agent:
> What is BBCA's free float, and who is its largest holder?
It should call `get_shareholders` and answer with the free float and
DWIMURIA INVESTAMA ANDALAN, the largest holder.
See [all tools](/mcp/tools/).

115
web/src/content/docs/mcp/tools.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Tools
description: Every idx-mcp tool and its inputs, generated from the server's tool list.
---
<!-- Generated by web/scripts/gen-mcp-tools.sh; do not edit by hand. -->
idx-mcp serves these tools. `ownership_sync` is listed only when the server
starts with `--allow-sync`. Results that come from a live provider are wrapped
as `{data, source, fetched_at, stale}`; failures return `{error, code,
message}` with `isError` set.
## `analyze_stock`
Analyze one IDX ticker: technical signals (trend, RSI, MACD, moving averages) and fundamental growth, valuation, and risk ratings. Analyses that fail are listed under `errors`; the call fails only if every analysis fails.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `kinds` | array of `technical` / `growth` / `valuation` / `risk` | no | Analyses to run (default: all). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |
## `compare_stocks`
Compare fundamental reports (growth, valuation, risk) across IDX tickers. Tickers that fail are listed under `failures`.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `symbols` | array of string | yes | IDX tickers, e.g. ["BBCA", "BBRI"]; the `.JK` suffix is optional. At most 20. |
## `get_company`
Company data for one IDX ticker: profile, financial statements, earnings, analyst sentiment, insights, and news. Sections that fail are listed under `errors`; the call fails only if every section fails.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `sections` | array of `profile` / `financials` / `earnings` / `sentiment` / `insights` / `news` | no | Sections to fetch (default: all). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |
## `get_investor_holdings`
Every IDX holding (above 1%) of one investor, matched by name.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `entity` | string | yes | Investor name or part of it, e.g. "DWIMURIA"; the closest match is used. |
## `get_ownership_changes`
Holder changes (new, exit, increase, decrease) between two KSEI release dates, optionally for one ticker.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | Earlier release date, YYYY-MM-DD (see ownership_status). |
| `limit` | integer | no | Maximum rows returned (default 200, at most 2000); `total` reports the full count. |
| `ticker` | string | no | Only this ticker's changes. |
| `to` | string | yes | Later release date, YYYY-MM-DD. |
## `get_price_history`
OHLCV price history for one IDX ticker.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `interval` | `1d` / `1wk` / `1mo` | no | Candle size (default "1d"). |
| `period` | `1d` / `5d` / `1mo` / `3mo` / `6mo` / `1y` / `2y` / `5y` | no | Lookback window (default "3mo"). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |
## `get_quotes`
Latest quotes (price, change, volume, 52-week range, market cap) for one or more IDX tickers.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `symbols` | array of string | yes | IDX tickers, e.g. ["BBCA", "BBRI"]; the `.JK` suffix is optional. At most 20. |
## `get_shareholders`
Shareholders above 1% of an IDX ticker from the latest KSEI release, with concentration metrics (top1, top3, HHI, free float).
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `ticker` | string | yes | IDX ticker, e.g. "BBCA". |
## `ownership_status`
Ownership database status: whether it has data, and the imported KSEI release dates.
No inputs.
## `ownership_sync`
Download or refresh the KSEI ownership snapshot (several MB) into the local database.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `force` | boolean | no | Re-download even when the local snapshot is current. |
## `screen_stocks`
Run a stock screen (top/worst performers, high dividend, low P/E, 52-week highs/lows, high volume, large cap).
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | `top-performers` / `worst-performers` / `high-dividend` / `low-pe` / `52w-high` / `52w-low` / `high-volume` / `large-cap` | no | Screen to run (default "top-performers"). |
| `limit` | integer | no | Maximum results (default 50, at most 200). |
| `region` | `id` / `us` / `sg` / `hk` / `jp` | no | Market region (default "id"). |
## `search_investors`
Search investor names in the KSEI ownership database.
| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Maximum results (default 20, at most 100). |
| `query` | string | yes | Full-text query over investor names. |

75
web/src/content/docs/start/config.md Normal file
View file

@ -0,0 +1,75 @@
---
title: Configuration
description: Config file, environment variables and their precedence.
---
idx works without configuration. To change defaults, use the config file,
environment variables or flags. When they disagree, the first one wins:
1. command-line flags
2. environment variables
3. the config file
4. built-in defaults
## Config file
`~/.config/idx/config.toml` (or `$XDG_CONFIG_HOME/idx/config.toml`):
```bash
idx config init # write the defaults below
idx config set general.output json
idx config get cache.quote_ttl
idx config path
```
```toml
[general]
provider = "msn" # msn | yahoo
history_provider = "auto" # auto | yahoo | msn
exchange = "JK"
output = "auto" # auto | table | json | jsonl
color = true
[cache]
quote_ttl = 300 # seconds
fundamental_ttl = 3600
[ownership]
# db_path = "/path/to/ownership.db"
# snapshot_manifest = "https://..."
```
## Environment variables
| Variable | Overrides |
| --- | --- |
| `IDX_PROVIDER` | `general.provider` |
| `IDX_HISTORY_PROVIDER` | `general.history_provider` |
| `IDX_EXCHANGE` | `general.exchange` |
| `IDX_OUTPUT` | `general.output` |
| `IDX_NO_COLOR` | `general.color` (`1` or `true` disables colour) |
| `IDX_CACHE_QUOTE_TTL` | `cache.quote_ttl` |
| `IDX_CACHE_FUNDAMENTAL_TTL` | `cache.fundamental_ttl` |
| `IDX_OWNERSHIP_SNAPSHOT_MANIFEST` | `ownership.snapshot_manifest` |
| `IDX_CURL_IMPERSONATE_BIN` | path to a `curl_chrome*` binary |
## Files idx keeps
| What | Where |
| --- | --- |
| Config | `~/.config/idx/config.toml` |
| Cache | `~/.cache/idx/` (`idx cache info`, `idx cache clear`) |
| Ownership database | `~/.local/share/idx/ownership.db` |
The MCP server reads the same config, cache and database.
## Offline and caching
Quotes are cached for `quote_ttl` seconds and fundamentals for
`fundamental_ttl`. `--offline` makes no network requests and serves cached
data, even when stale; `--no-cache` always fetches.
:::note
A config created by `idx config init` before v0.3 pins `output = "table"`.
Run `idx config set general.output auto` to get JSON when piped.
:::

98
web/src/content/docs/start/install.mdx Normal file
View file

@ -0,0 +1,98 @@
---
title: Install
description: Install idx with npm, the install script, Cargo or Nix.
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
Prebuilt binaries cover Linux x64/arm64 (static) and macOS arm64/x64. On
Windows, use WSL.
:::tip[Let your agent do it]
Paste this into Claude Code, Codex, Cursor or another coding agent:
```text wrap
Install idx-cli and its MCP server for me by following https://idx.rasyidanaf.com/agents/install.md, then show me that it works.
```
:::
<Tabs syncKey="install">
<TabItem label="npm">
```bash
npm install --global idx-cli
npx idx-cli --help # or run without installing
```
The package downloads the 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`.
</TabItem>
<TabItem label="Install script">
```bash
curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh
```
Downloads the 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:
```bash
curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.3.1 --dir ~/bin
```
</TabItem>
<TabItem label="Cargo">
```bash
cargo install idx-cli
```
Builds from source. Requires Rust 1.89 or newer.
</TabItem>
<TabItem label="Nix">
```bash
nix profile install github:0xrsydn/idx-cli
nix run github:0xrsydn/idx-cli -- version # or run without installing
```
The Nix package bundles the helper tools below.
</TabItem>
</Tabs>
Check it works:
```bash
idx version
```
## Helper tools
Everyday use needs nothing else: stock data with the default MSN provider,
price history, `ownership sync` and every local ownership query. A few
commands call external tools:
| Tool | Needed for |
| --- | --- |
| `curl_chrome*` from [curl-impersonate](https://github.com/lexiforest/curl-impersonate), or `IDX_CURL_IMPERSONATE_BIN` | `ownership discover` and `ownership import --url` (IDX sits behind Cloudflare), and Yahoo fundamentals with `IDX_PROVIDER=yahoo` |
| `mutool` from MuPDF | importing legacy PDF ownership reports |
## The MCP server
`idx-mcp` installs the same ways (`npx -y idx-mcp`, `cargo install idx-mcp`,
or `nix profile install github:0xrsydn/idx-cli#idx-mcp`). See
[MCP setup](/mcp/setup/).
## Shell completions
```bash
idx completions bash > ~/.local/share/bash-completion/completions/idx
idx completions zsh > "${fpath[1]}/_idx"
idx completions fish > ~/.config/fish/completions/idx.fish
```

50
web/src/content/docs/start/quickstart.md Normal file
View file

@ -0,0 +1,50 @@
---
title: Quickstart
description: First stock and ownership commands.
---
## Stocks
Tickers are IDX codes; the `.JK` suffix is optional.
```bash
idx stocks quote BBCA # one quote
idx stocks quote BBCA BBRI BMRI # several (spaces or commas)
idx stocks history BBCA --period 1y # daily OHLCV
idx stocks technical BBCA # trend, RSI, MACD, moving averages
idx stocks fundamental BBCA # growth, valuation and risk together
idx stocks compare BBCA BBRI BMRI # fundamentals side by side
idx stocks screen --filter high-dividend
```
## Ownership
Ownership data comes from the monthly KSEI register of holders above 1%.
Download the maintained snapshot once; after that every query runs offline.
```bash
idx ownership sync # a few MB, safe to rerun
idx ownership ticker BBCA # who holds BBCA
idx ownership entity "ANTHONI SALIM" # everything one investor holds
idx ownership search salim # find investor names
idx ownership releases # which months you have
idx ownership changes --from 2026-08-31 --to 2026-09-30
```
## JSON
In a terminal idx prints tables. When its output is piped or captured it
prints JSON, so scripts and agents need no flag:
```bash
idx stocks quote BBCA BBRI | jq -r '.[] | "\(.symbol) \(.price)"'
idx -o json stocks quote BBCA # force JSON in a terminal
```
See [Output and exit codes](/cli/output/) for the full contract.
## Next
- [Stocks guide](/cli/stocks/) and [ownership guide](/cli/ownership/)
- [Configuration](/start/config/)
- [Use idx from an AI agent](/mcp/setup/)