Configuration

Precedence, highest first: command-line flags → IDX_* environment variables → config file → built-in defaults.

Config file

Override the location with --config PATH or IDX_CONFIG=PATH.

idx config init                       # write a commented template
idx config set provider yahoo
idx config set history_provider stockbit   # candles from your Stockbit session
idx config set cache.quote_ttl_secs 120
idx config get                        # effective settings after all layers
idx config get provider               # one key, as stored in the file
idx config path

provider = "auto"      # auto | yahoo | msn | stockbit
history_provider = "auto"  # auto | yahoo | stockbit: where candles come from
output = "table"       # auto | table | json | jsonl | csv
color = "auto"         # auto | always | never
timeout_secs = 15
exchange = "JK"        # Yahoo suffix for bare tickers in the Yahoo-backed commands

[cache]
dir = "/custom/cache/dir"
quote_ttl_secs = 60
history_ttl_secs = 3600

[stockbit]
# session = "/path/to/stockbit-session.json"   # `idx stockbit login` writes it

Environment variables

Output on a terminal and in a pipe

table stays the default whether stdout is a terminal or not, so existing idx ... > file and | grep pipelines keep reading tables. Opt in to output = "auto" (or IDX_OUTPUT=auto) for a table on a terminal and the JSON envelope whenever stdout is piped or captured, which suits agents that forget -o json. idx config get shows the setting next to what it resolves to (output_setting and output in its JSON).

Errors and the commands that need no data source (version, schema, config, mcp setup) resolve the format the same way, flag first, then IDX_OUTPUT, then the config file; a layer that does not parse is skipped there, so a broken setting still gets a readable error.

Other markets (exchange)

Yahoo Finance lists IDX shares under .JK, which idx adds for you. The Yahoo-backed commands also take a ticker from another Yahoo market with its suffix (idx stocks history D05.SI), or bare once exchange says which market (idx config set exchange SI, then idx stocks history D05). .JK always means IDX, and every other command (brief, screen, news, broker, bandar, foreign, actions, market, ownership, stockbit) reads IDX tickers only and refuses D05.SI with exit 2. MSN and Stockbit cover IDX only, so with --provider auto Yahoo answers for other markets. Saved watchlist entries keep their suffix (D05.SI), so changing exchange later does not change them. For the same reason idx's own output piped back through - (-o json, -o jsonl, a watchlist file) reads a bare code as IDX; only typed text on stdin follows exchange. MCP tools take explicit suffixes but do not use IDX_EXCHANGE: a bare code is always IDX there. An invalid value still stops idx mcp from starting, as any invalid setting does.

History provider

history_provider decides where candles come from, separately from provider. Every command that reads candles follows it: stocks history, technical, returns, brief, bandar price moves, watch returns and the MCP tools behind them.

Stockbit picks the bar size from the window, so under provider = "stockbit" a 2y or 5y daily request would come back weekly and feed weekly returns into daily analytics; auto sends those to Yahoo and says so in a warning. A fallback after a Stockbit failure is a warning too (stockbit history failed (...); candles from yahoo), and the JSON envelope's provider names the source the candles came from. history_provider = "stockbit" with the default provider = "auto" keeps the free providers for quotes and fundamentals and takes only candles from Stockbit; a request it does not serve as asked then carries a warning naming the bars and span it returned (--period 1mo --interval 1h comes back as one week of hourly bars).

Cache

Each response is stored as one JSON file named by the SHA-256 of its cache key. Freshness is judged against the TTL in effect when you read, so changing a TTL applies immediately.

• --offline: serve whatever is cached, fresh or stale; exit 5 on a miss.
• --no-cache: always fetch; the result is still written for later.
• --offline with an entry older than its TTL: the entry is served with stale: true and stale_reason: "offline".
• Network failure with a stale entry present: the stale entry is served with stale: true, stale_reason: "fetch_failed" and a warning naming the failure (live fetch failed (...); showing cached copy). Table mode prints the warnings and warning: showing stale cached data from <fetch time> WIB to stderr.
• idx.co.id's bot protection (Cloudflare) refusing a request counts as such a failure. A challenged request is asked again after 5, 10 and 15 s (four tries, at most 30 s of waiting per request; the loading line shows www.idx.co.id retry 1); one met by a block page is not. A refusal is never cached. For a minute after a challenge lasts through every pause, the next idx.co.id requests (from any command or MCP call on the same cache, --no-cache aside) are asked once, so a command that makes several meets the refusal or its cached copies at once instead of waiting 30 s for each. market brokers under --source auto asks idx.co.id once, without the pauses, where IPOT could answer for the session asked for, and lets IPOT stand in; only if IPOT cannot is idx.co.id asked again with every pause. An empty copy of a day's stock, broker or index summary does not stand in for a failed fetch, as it may be from before the summary was out: the error stands and names the copy. So does a copy of a stock's history without a session in the stocks foreign --from/--to range. With nothing cached the error is blocked (exit 3) and says what to do; under --no-cache it says the cache was skipped and that --offline serves a copy if there is one.
• idx.co.id's day summaries (stock, broker, index) are kept for 30 days once the session is over, and for 15 minutes on the day itself. An empty one cached on or before its own day, before the summary was out, keeps the 15 minutes on later days too, so it is asked again instead of passing for a day without trading.
• Network error text and warnings never include a URL's query string, and cache keys never hold a session token, so the Yahoo crumb and the MSN key stay out of every message; -vv debug logging still prints full request URLs.
• News feeds: a feed that times out or refuses the connection is not asked again for five minutes. Until then its cached copy is served with a warning naming the failure, or the warning alone when nothing is cached, so one silent feed does not make every call wait out --timeout. --no-cache asks anyway.

idx cache stats
idx cache clear
idx cache path

The Yahoo session (anonymous cookie + crumb) is cached for six hours under the same directory. idx cache clear removes it too.