0xrsydn/idx-cli
1
mirror of https://github.com/0xrsydn/idx-cli.git synced 2026-11-07 01:35:36 +00:00
Code Issues Projects Releases 1 Packages Wiki Activity
idx-cli/web/src/content/docs/agents/index.md
hermes b236c7f9d9 fix(ownership): report a Cloudflare challenge as its own error and result 
When Cloudflare answers idx.co.id with a challenge, curl fails with only
`curl: (22)`, which exits 4 like any other HTTP failure, and every profile
is tried twice. A challenge needs a browser, so no profile can solve it. The
source is monthly, so the publisher only needs one run per month to get
through: treat a challenge as "retry tomorrow" and alert on stale data.

- Add IdxError::CloudflareChallenge (CLOUDFLARECHALLENGE, exit 6), detected
  from the cf-mitigated header. curl reports it on stderr through --write-out,
  because --fail drops the response.
- A URL with a challenge gets one round of profiles; other failures keep two.
  This also covers `stocks flow --source idx`, which now exits 6 on a challenge.
- -v logs which profile fetched each URL.
- Discovery keeps error types, so a challenge survives an announcement miss.
  A source answering with something unparseable still is not called a challenge.
- `ownership discover --require-data-page` fails when the data page cannot be
  read. Default discover is unchanged: it warns and lists older announcements.
- The publisher and builder use that flag, so a failed data page can no longer
  end in a false "up-to-date". A challenge ends in `RESULT: blocked stage=<stage>`,
  exit 6; every other failure stays `RESULT: FAILED`.
- The systemd example treats exit 6 as success and runs the freshness check, so
  the unit fails on FAILED or on stale data.
- live-smoke reports a challenge as CHALLENGED, a failure and never a pass.

Golden change: completions-bash.golden gains `--require-data-page` in the
discover options, one word on one line. It is the direct result of the new flag;
no other golden file changes.

Live check on 2026-11-05 against release/v0.5.0: 19 passed, 2 failed. Both
failures are real challenges (flow-idx, discover), each exit 6 with empty stdout.
The import, releases and ticker cases did not run, because discover did not pass.

Refs #83
2026-11-05 09:50:12 +00:00

2.3 KiB
Raw Blame History

title description
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): 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, 6 Cloudflare challenge from idx.co.id, retry later, 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

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