<SYSTEM>This is the full developer documentation for idx-cli</SYSTEM>

# About the data

> Where idx's data comes from, how fresh it is, and the project's terms.

## Sources

[Section titled “Sources”](#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

[Section titled “The ownership snapshot”](#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

[Section titled “Terms”](#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.

# Using idx from an agent

> 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

[Section titled “Using the CLI”](#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

[Section titled “Recipes”](#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

[Section titled “Skill file”](#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

[Section titled “Machine-readable docs”](#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).

# Agent-led install

> 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

[Section titled “1. Check the platform”](#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

[Section titled “2. Install idx”](#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

[Section titled “3. Register idx-mcp with yourself”](#3-register-idx-mcp-with-yourself)

Work out which harness you are, then apply its setup below. If you installed the `idx-mcp` binary instead of using Node.js, use the command `idx-mcp` with no arguments in place of `npx -y idx-mcp`. For any other harness, find how it registers a stdio MCP server, and ask the user if unsure.

* Claude Code

  Run in a terminal

  ```bash
  claude mcp add idx -- npx -y idx-mcp
  ```

* Codex

  `~/.codex/config.toml`

  ```toml
  [mcp_servers.idx]
  command = "npx"
  args = ["-y", "idx-mcp"]
  ```

* Cursor

  `~/.cursor/mcp.json (or .cursor/mcp.json in a project)`

  ```json
  {
    "mcpServers": {
      "idx": { "command": "npx", "args": ["-y", "idx-mcp"] }
    }
  }
  ```

* opencode

  `~/.config/opencode/opencode.json (or opencode.json in a project)`

  ```json
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "idx": { "type": "local", "command": ["npx", "-y", "idx-mcp"], "enabled": true }
    }
  }
  ```

* pi

  `~/.pi/agent/mcp.json`

  ```json
  {
    "mcpServers": {
      "idx": { "command": "npx", "args": ["-y", "idx-mcp"], "exposure": "direct" }
    }
  }
  ```

* Hermes

  `~/.hermes/config.yaml`

  ```yaml
  mcp_servers:
    idx:
      command: npx
      args: ["-y", "idx-mcp"]
      enabled: true
  ```

* Other

  Any MCP client that runs stdio servers

  ```text
  command: npx
  args: -y idx-mcp
  # or the command idx-mcp, if installed
  # add --allow-sync to expose ownership_sync
  ```

Merge into existing files; never overwrite other servers or settings.

## 4. Download ownership data

[Section titled “4. Download ownership data”](#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

[Section titled “5. Verify”](#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

[Section titled “6. Report to the user”](#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?”

# Output and exit codes

> Tables, JSON, errors and exit codes; the contract scripts and agents rely on.

## Formats

[Section titled “Formats”](#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

[Section titled “The contract”](#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

[Section titled “Exit codes”](#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

[Section titled “Pipes”](#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.

# Ownership

> 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

[Section titled “Get the data”](#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

[Section titled “Queries”](#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

[Section titled “Import reports yourself”](#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

[Section titled “Entity names”](#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.

# Command reference

> Every idx command and flag, generated from idx --help.

This page is generated from `idx --help`, so it always matches the released CLI. For explanations and examples, see the [stocks](/cli/stocks/) and [ownership](/cli/ownership/) guides.

## `idx`

[Section titled “idx”](#idx)

```text
idx-cli is a Rust command-line tool for Indonesian stock market (IDX) analysis.
It supports quote lookup, historical data, local caching, and output formats for both humans and AI agents.


Usage: idx [OPTIONS] <COMMAND>


Commands:
  stocks       Stock data and analysis
  config       Manage configuration
  cache        Manage local cache
  ownership    Ownership intelligence (bootstrap with `ownership sync`)
  completions  Generate shell completions
  version      Show idx-cli version
  help         Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped]


          [possible values: auto, table, json, jsonl]


      --no-color
          Disable colored output


  -q, --quiet
          Suppress non-essential output


  -v, --verbose...
          Increase verbosity (-v, -vv)


      --offline
          Run without network requests


      --no-cache
          Bypass local cache


  -h, --help
          Print help (see a summary with '-h')
```

## `idx stocks`

[Section titled “idx stocks”](#idx-stocks)

```text
Stock data and analysis


Usage: idx stocks [OPTIONS] <COMMAND>


Commands:
  quote        Get real-time stock quotes
  history      Get historical OHLC data
  technical    Run technical analysis on a stock
  growth       Run growth analysis on a stock
  valuation    Run valuation analysis on a stock
  risk         Run risk analysis on a stock
  fundamental  Run full fundamental analysis on a stock
  profile      Get company profile
  financials   Get financial statements
  earnings     Get earnings report
  sentiment    Get crowd sentiment
  insights     Get AI insights
  news         Get stock news
  screen       MSN screener
  compare      Compare fundamentals across stocks
  help         Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks quote`

[Section titled “idx stocks quote”](#idx-stocks-quote)

```text
Get real-time stock quotes


Usage: idx stocks quote [OPTIONS] <SYMBOLS>...


Arguments:
  <SYMBOLS>...  One or more symbols, comma-separated or space-separated; `-` reads them from stdin


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks quote BBCA
  idx stocks quote BBCA,BBRI,BMRI
  idx -o json stocks quote BBCA
  echo BBCA BBRI | idx stocks quote -
```

### `idx stocks history`

[Section titled “idx stocks history”](#idx-stocks-history)

```text
Get historical OHLC data


Usage: idx stocks history [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --period <PERIOD>
          [default: 3mo] [possible values: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y]
      --interval <INTERVAL>
          [default: 1d] [possible values: 1d, 1wk, 1mo]
      --no-color
          Disable colored output
      --history-provider <HISTORY_PROVIDER>
          [possible values: auto, yahoo, msn]
  -q, --quiet
          Suppress non-essential output
  -v, --verbose...
          Increase verbosity (-v, -vv)
      --offline
          Run without network requests
      --no-cache
          Bypass local cache
  -h, --help
          Print help


Examples:
  idx stocks history BBCA --period 3mo
  idx stocks history BBCA --period 1y --interval 1wk
```

### `idx stocks technical`

[Section titled “idx stocks technical”](#idx-stocks-technical)

```text
Run technical analysis on a stock


Usage: idx stocks technical [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
      --history-provider <HISTORY_PROVIDER>
          [possible values: auto, yahoo, msn]
  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color
          Disable colored output
  -q, --quiet
          Suppress non-essential output
  -v, --verbose...
          Increase verbosity (-v, -vv)
      --offline
          Run without network requests
      --no-cache
          Bypass local cache
  -h, --help
          Print help


Examples:
  idx stocks technical BBCA
  idx -o json stocks technical BBCA
```

### `idx stocks growth`

[Section titled “idx stocks growth”](#idx-stocks-growth)

```text
Run growth analysis on a stock


Usage: idx stocks growth [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks growth BBCA
  idx -o json stocks growth BBCA
```

### `idx stocks valuation`

[Section titled “idx stocks valuation”](#idx-stocks-valuation)

```text
Run valuation analysis on a stock


Usage: idx stocks valuation [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks valuation BBCA
  idx -o json stocks valuation BBCA
```

### `idx stocks risk`

[Section titled “idx stocks risk”](#idx-stocks-risk)

```text
Run risk analysis on a stock


Usage: idx stocks risk [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks risk BBCA
  idx -o json stocks risk BBCA
```

### `idx stocks fundamental`

[Section titled “idx stocks fundamental”](#idx-stocks-fundamental)

```text
Run full fundamental analysis on a stock


Usage: idx stocks fundamental [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>  Single ticker symbol (e.g. BBCA)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks fundamental BBCA
  idx -o json stocks fundamental BBCA
```

### `idx stocks profile`

[Section titled “idx stocks profile”](#idx-stocks-profile)

```text
Get company profile


Usage: idx stocks profile [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks financials`

[Section titled “idx stocks financials”](#idx-stocks-financials)

```text
Get financial statements


Usage: idx stocks financials [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>           Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --statement <STATEMENT>...  Limit output to one or more statements [possible values: income, balance, cashflow]
      --no-color                  Disable colored output
  -q, --quiet                     Suppress non-essential output
  -v, --verbose...                Increase verbosity (-v, -vv)
      --offline                   Run without network requests
      --no-cache                  Bypass local cache
  -h, --help                      Print help


Examples:
  idx stocks financials BBCA
  idx stocks financials BBCA --statement income
  idx stocks financials BBCA --statement income,balance
```

### `idx stocks earnings`

[Section titled “idx stocks earnings”](#idx-stocks-earnings)

```text
Get earnings report


Usage: idx stocks earnings [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
      --forecast         Only include forward earnings rows
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --history          Only include historical earnings rows
      --no-color         Disable colored output
      --annual           Only include annual periods
  -q, --quiet            Suppress non-essential output
      --quarterly        Only include quarterly periods
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks earnings BBCA
  idx stocks earnings BBCA --history --quarterly
  idx -o json stocks earnings BBCA --forecast --annual
```

### `idx stocks sentiment`

[Section titled “idx stocks sentiment”](#idx-stocks-sentiment)

```text
Get crowd sentiment


Usage: idx stocks sentiment [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks insights`

[Section titled “idx stocks insights”](#idx-stocks-insights)

```text
Get AI insights


Usage: idx stocks insights [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks news`

[Section titled “idx stocks news”](#idx-stocks-news)

```text
Get stock news


Usage: idx stocks news [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
      --limit <LIMIT>    [default: 10]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks screen`

[Section titled “idx stocks screen”](#idx-stocks-screen)

```text
MSN screener


Usage: idx stocks screen [OPTIONS]


Options:
      --filter <FILTER>  [default: top-performers]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
      --region <REGION>  [default: id]
      --limit <LIMIT>    [default: 50]
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx stocks compare`

[Section titled “idx stocks compare”](#idx-stocks-compare)

```text
Compare fundamentals across stocks


Usage: idx stocks compare [OPTIONS] <SYMBOLS>...


Arguments:
  <SYMBOLS>...  One or more symbols, comma-separated or space-separated; `-` reads them from stdin


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx stocks compare BBCA BBRI BMRI
  idx stocks compare BBCA,BBRI,BMRI
  idx -o json stocks compare BBCA,BBRI
  idx stocks screen --filter low-pe | jq -r '.[].symbol' | idx stocks compare -
```

## `idx config`

[Section titled “idx config”](#idx-config)

```text
Manage configuration


Usage: idx config [OPTIONS] <COMMAND>


Commands:
  init  Create default configuration file
  get   Get a configuration value by key
  set   Set a configuration value by key
  path  Print configuration file path
  help  Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx config init`

[Section titled “idx config init”](#idx-config-init)

```text
Create default configuration file


Usage: idx config init [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx config get`

[Section titled “idx config get”](#idx-config-get)

```text
Get a configuration value by key


Usage: idx config get [OPTIONS] <KEY>


Arguments:
  <KEY>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx config set`

[Section titled “idx config set”](#idx-config-set)

```text
Set a configuration value by key


Usage: idx config set [OPTIONS] <KEY> <VALUE>


Arguments:
  <KEY>
  <VALUE>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx config path`

[Section titled “idx config path”](#idx-config-path)

```text
Print configuration file path


Usage: idx config path [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

## `idx cache`

[Section titled “idx cache”](#idx-cache)

```text
Manage local cache


Usage: idx cache [OPTIONS] <COMMAND>


Commands:
  info   Show cache usage information
  clear  Clear all cached files
  help   Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx cache info`

[Section titled “idx cache info”](#idx-cache-info)

```text
Show cache usage information


Usage: idx cache info [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx cache clear`

[Section titled “idx cache clear”](#idx-cache-clear)

```text
Clear all cached files


Usage: idx cache clear [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

## `idx ownership`

[Section titled “idx ownership”](#idx-ownership)

```text
Ownership intelligence (KSEI + Bing).


Preferred bootstrap path:
  1. Run `idx ownership sync` to install or refresh a maintained SQLite snapshot.
  2. If no snapshot manifest is available, run `idx ownership discover` and then `idx ownership import --url <pdf-url>`.
  3. Local `.xlsx`, `.pdf`, `.zip`, and `.txt` imports remain available for manual or fallback workflows.


Usage: idx ownership [OPTIONS] <COMMAND>


Commands:
  discover       Discover the latest IDX-hosted ownership report URLs
  import         Import ownership data directly from source files
  sync           Install or refresh a maintained ownership SQLite snapshot
  ticker         Show all holders for a ticker (KSEI + Bing combined)
  entity         Show all holdings for an entity across tickers
  search         Search entities by name
  cross-holders  Rank entities by cross-ownership breadth
  concentration  Rank tickers by ownership concentration
  flow           Show Bing institutional flow for a ticker
  changes        Diff two KSEI releases
  graph          Ownership network graph
  resolve        Manual entity resolution workflow
  releases       List imported KSEI releases
  help           Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped]


          [possible values: auto, table, json, jsonl]


      --no-color
          Disable colored output


  -q, --quiet
          Suppress non-essential output


  -v, --verbose...
          Increase verbosity (-v, -vv)


      --offline
          Run without network requests


      --no-cache
          Bypass local cache


  -h, --help
          Print help (see a summary with '-h')


Examples:
  idx ownership sync
  idx ownership sync --manifest /path/to/ownership-snapshot-manifest.json
  idx ownership discover --limit 1
  idx ownership import --url <pdf-url>
  idx ownership releases
```

### `idx ownership discover`

[Section titled “idx ownership discover”](#idx-ownership-discover)

```text
Discover the latest IDX-hosted ownership report URLs


Usage: idx ownership discover [OPTIONS]


Options:
      --family <FAMILY>  Report family to discover: above1 (default), all, above5, or investor-type [default: above1]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --limit <LIMIT>    Maximum number of discovered report URLs to print [default: 6]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help


Examples:
  idx ownership discover --limit 1
  idx ownership discover --family all --limit 6


Use this when no snapshot manifest is available and you need a direct XLSX or PDF URL for `idx ownership import --url`.
```

### `idx ownership import`

[Section titled “idx ownership import”](#idx-ownership-import)

```text
Import ownership data directly from source files.


Prefer `idx ownership sync` for normal bootstrap/update flows. Use `import` when you need a direct PDF import from IDX discovery output, a local PDF, or a local KSEI archive fallback file.


Usage: idx ownership import [OPTIONS]


Options:
  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped]


          [possible values: auto, table, json, jsonl]


      --url <URL>
          Direct URL to a remote above-1% XLSX or PDF, typically from `ownership discover`


      --file <FILE>
          Path to a local ownership file: above-1% XLSX or PDF (primary), ZIP/TXT archive (fallback)


      --no-color
          Disable colored output


      --fetch-bing <FETCH_BING>
          Fetch Bing institutional data for these symbols


  -q, --quiet
          Suppress non-essential output


      --force
          Re-import even if the release SHA-256 has already been seen


  -v, --verbose...
          Increase verbosity (-v, -vv)


      --offline
          Run without network requests


      --no-cache
          Bypass local cache


  -h, --help
          Print help (see a summary with '-h')


Examples:
  idx ownership import --url <pdf-url-from-discover>
  idx ownership import --file /path/to/peng-2026-08-00017-satu-persen.xlsx
  idx ownership import --file /path/to/ksei.pdf
  idx ownership import --file /path/to/BalanceposEfek20260227.zip
```

### `idx ownership sync`

[Section titled “idx ownership sync”](#idx-ownership-sync)

```text
Install or refresh a maintained ownership SQLite snapshot.


This is the normal bootstrap/update path for ownership data.


Manifest lookup order:
  1. `--manifest`
  2. `IDX_OWNERSHIP_SNAPSHOT_MANIFEST`
  3. `ownership.snapshot_manifest` in config


Usage: idx ownership sync [OPTIONS]


Options:
      --manifest <MANIFEST>
          Snapshot manifest location (URL or local path). If omitted, idx falls back through env/config and then the published default URL


  -o, --output <OUTPUT>
          Output format [default: auto = table on a terminal, json when piped]


          [possible values: auto, table, json, jsonl]


      --force
          Replace the local DB even when it is already current or newer than the snapshot


      --no-color
          Disable colored output


  -q, --quiet
          Suppress non-essential output


  -v, --verbose...
          Increase verbosity (-v, -vv)


      --offline
          Run without network requests


      --no-cache
          Bypass local cache


  -h, --help
          Print help (see a summary with '-h')


Examples:
  idx ownership sync
  idx ownership sync --manifest /path/to/ownership-snapshot-manifest.json
  IDX_OWNERSHIP_SNAPSHOT_MANIFEST=https://example.com/latest.json idx ownership sync


If none of the above are set, `ownership sync` falls back to the built-in published manifest URL.
```

### `idx ownership ticker`

[Section titled “idx ownership ticker”](#idx-ownership-ticker)

```text
Show all holders for a ticker (KSEI + Bing combined)


Usage: idx ownership ticker [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --source <SOURCE>  [default: all]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership entity`

[Section titled “idx ownership entity”](#idx-ownership-entity)

```text
Show all holdings for an entity across tickers


Usage: idx ownership entity [OPTIONS] <NAME>


Arguments:
  <NAME>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership search`

[Section titled “idx ownership search”](#idx-ownership-search)

```text
Search entities by name


Usage: idx ownership search [OPTIONS] <QUERY>


Arguments:
  <QUERY>


Options:
      --limit <LIMIT>    [default: 20]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership cross-holders`

[Section titled “idx ownership cross-holders”](#idx-ownership-cross-holders)

```text
Rank entities by cross-ownership breadth


Usage: idx ownership cross-holders [OPTIONS]


Options:
  -o, --output <OUTPUT>            Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --top <TOP>                  [default: 20]
      --min-tickers <MIN_TICKERS>  [default: 2]
      --no-color                   Disable colored output
  -q, --quiet                      Suppress non-essential output
  -v, --verbose...                 Increase verbosity (-v, -vv)
      --offline                    Run without network requests
      --no-cache                   Bypass local cache
  -h, --help                       Print help
```

### `idx ownership concentration`

[Section titled “idx ownership concentration”](#idx-ownership-concentration)

```text
Rank tickers by ownership concentration


Usage: idx ownership concentration [OPTIONS]


Options:
      --by <BY>          [default: hhi]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
      --top <TOP>        [default: 20]
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership flow`

[Section titled “idx ownership flow”](#idx-ownership-flow)

```text
Show Bing institutional flow for a ticker


Usage: idx ownership flow [OPTIONS] <SYMBOL>


Arguments:
  <SYMBOL>


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership changes`

[Section titled “idx ownership changes”](#idx-ownership-changes)

```text
Diff two KSEI releases


Usage: idx ownership changes [OPTIONS] --from <FROM> --to <TO>


Options:
      --from <FROM>
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
      --to <TO>
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership graph`

[Section titled “idx ownership graph”](#idx-ownership-graph)

```text
Ownership network graph


Usage: idx ownership graph [OPTIONS] <ROOT>


Arguments:
  <ROOT>  Ticker code or entity name to start from


Options:
      --depth <DEPTH>    Traversal depth (default 2) [default: 2]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --format <FORMAT>  Output format: table or dot (Graphviz) [default: table]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership resolve`

[Section titled “idx ownership resolve”](#idx-ownership-resolve)

```text
Manual entity resolution workflow


Usage: idx ownership resolve [OPTIONS] <COMMAND>


Commands:
  unresolved  List unresolved or low-confidence entity aliases
  map         Manually map a raw investor name to a canonical entity name
  merge       Merge two entities (keep first, merge second into it)
  help        Print this message or the help of the given subcommand(s)


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

#### `idx ownership resolve unresolved`

[Section titled “idx ownership resolve unresolved”](#idx-ownership-resolve-unresolved)

```text
List unresolved or low-confidence entity aliases


Usage: idx ownership resolve unresolved [OPTIONS]


Options:
      --limit <LIMIT>    [default: 50]
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

#### `idx ownership resolve map`

[Section titled “idx ownership resolve map”](#idx-ownership-resolve-map)

```text
Manually map a raw investor name to a canonical entity name


Usage: idx ownership resolve map [OPTIONS] <ALIAS> <ENTITY>


Arguments:
  <ALIAS>   The raw name as it appears in the data
  <ENTITY>  The canonical entity name to map to


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

#### `idx ownership resolve merge`

[Section titled “idx ownership resolve merge”](#idx-ownership-resolve-merge)

```text
Merge two entities (keep first, merge second into it)


Usage: idx ownership resolve merge [OPTIONS] <KEEP> <MERGE>


Arguments:
  <KEEP>   Entity ID to keep
  <MERGE>  Entity ID to merge and delete


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

### `idx ownership releases`

[Section titled “idx ownership releases”](#idx-ownership-releases)

```text
List imported KSEI releases


Usage: idx ownership releases [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

## `idx completions`

[Section titled “idx completions”](#idx-completions)

```text
Generate shell completions


Usage: idx completions [OPTIONS] <SHELL>


Arguments:
  <SHELL>  [possible values: bash, zsh, fish]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

## `idx version`

[Section titled “idx version”](#idx-version)

```text
Show idx-cli version


Usage: idx version [OPTIONS]


Options:
  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
      --no-color         Disable colored output
  -q, --quiet            Suppress non-essential output
  -v, --verbose...       Increase verbosity (-v, -vv)
      --offline          Run without network requests
      --no-cache         Bypass local cache
  -h, --help             Print help
```

# Stocks

> 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

[Section titled “Quotes and history”](#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

[Section titled “Company data”](#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

[Section titled “Analysis”](#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

[Section titled “Screening”](#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

[Section titled “Providers”](#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/).

# MCP server

> 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/) (plus an opt-in `ownership_sync`): 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

[Section titled “Results”](#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

[Section titled “Limits”](#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

[Section titled “Ownership data”](#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).

# Set up idx-mcp

> Add idx-mcp to Claude Code, Codex, Cursor, opencode, pi, Hermes or any MCP client.

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
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

[Section titled “1. Get the server”](#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

[Section titled “2. Add it to your client”](#2-add-it-to-your-client)

* Claude Code

  Run in a terminal

  ```bash
  claude mcp add idx -- npx -y idx-mcp
  ```

* Codex

  `~/.codex/config.toml`

  ```toml
  [mcp_servers.idx]
  command = "npx"
  args = ["-y", "idx-mcp"]
  ```

* Cursor

  `~/.cursor/mcp.json (or .cursor/mcp.json in a project)`

  ```json
  {
    "mcpServers": {
      "idx": { "command": "npx", "args": ["-y", "idx-mcp"] }
    }
  }
  ```

* opencode

  `~/.config/opencode/opencode.json (or opencode.json in a project)`

  ```json
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "idx": { "type": "local", "command": ["npx", "-y", "idx-mcp"], "enabled": true }
    }
  }
  ```

* pi

  `~/.pi/agent/mcp.json`

  ```json
  {
    "mcpServers": {
      "idx": { "command": "npx", "args": ["-y", "idx-mcp"], "exposure": "direct" }
    }
  }
  ```

* Hermes

  `~/.hermes/config.yaml`

  ```yaml
  mcp_servers:
    idx:
      command: npx
      args: ["-y", "idx-mcp"]
      enabled: true
  ```

* Other

  Any MCP client that runs stdio servers

  ```text
  command: npx
  args: -y idx-mcp
  # or the command idx-mcp, if installed
  # add --allow-sync to expose ownership_sync
  ```

The Claude Code, Codex, opencode, pi and Hermes setups are the ones `tests/agents/agent-smoke.sh` drives with the real agents.

## 3. Get ownership data

[Section titled “3. Get ownership data”](#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

[Section titled “4. Check it works”](#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/).

# Tools

> Every idx-mcp tool and its inputs, generated from the server's tool list.

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`

[Section titled “analyze_stock”](#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`

[Section titled “compare_stocks”](#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`

[Section titled “get_company”](#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`

[Section titled “get_investor_holdings”](#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`

[Section titled “get_ownership_changes”](#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`

[Section titled “get_price_history”](#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`

[Section titled “get_quotes”](#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`

[Section titled “get_shareholders”](#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`

[Section titled “ownership_status”](#ownership_status)

Ownership database status: whether it has data, and the imported KSEI release dates.

No inputs.

## `ownership_sync`

[Section titled “ownership_sync”](#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`

[Section titled “screen_stocks”](#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`

[Section titled “search_investors”](#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.       |

# Configuration

> 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

[Section titled “Config file”](#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

[Section titled “Environment variables”](#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

[Section titled “Files idx keeps”](#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

[Section titled “Offline and caching”](#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.

# Install

> Install idx with npm, the install script, Cargo or Nix.

Prebuilt binaries cover Linux x64/arm64 (static) and macOS arm64/x64. On Windows, use WSL.

Let your agent do it

Paste this into Claude Code, Codex, Cursor or another coding agent:

```text
Install idx-cli and its MCP server for me by following https://idx.rasyidanaf.com/agents/install.md, then show me that it works.
```

* 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`.

* 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
  ```

* Cargo

  ```bash
  cargo install idx-cli
  ```

  Builds from source. Requires Rust 1.89 or newer.

* 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.

Check it works:

```bash
idx version
```

## Helper tools

[Section titled “Helper tools”](#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

[Section titled “The MCP server”](#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

[Section titled “Shell completions”](#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
```

# Quickstart

> First stock and ownership commands.

## Stocks

[Section titled “Stocks”](#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

[Section titled “Ownership”](#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

[Section titled “JSON”](#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

[Section titled “Next”](#next)

* [Stocks guide](/cli/stocks/) and [ownership guide](/cli/ownership/)
* [Configuration](/start/config/)
* [Use idx from an AI agent](/mcp/setup/)