config

Purpose

Show and manage the resolved project configuration sourced from .idx.yml at the Git project root.

Usage

idx config show
idx config get <key>

Subcommands

Subcommand Description
show Display the full resolved configuration table, flagging values that come from .idx.yml
get <key> Print the resolved value of a single configuration key

Arguments

  • show: no positional arguments.
  • get: one required argument — the configuration key (e.g. search.operator).

Flags

  • Global: --quiet, -q.

Behavior and Side Effects

  • Read-only command; no filesystem writes.
  • Config is resolved from .idx.yml at the Git project root.
  • Precedence chain: built-in defaults → .idx.yml → CLI flags.

    idx config show

  • 14 configurable keys are displayed with their resolved value, source, and original default for overridden keys.

idx config get <key>

  • Resolves the key against the current config (built-in defaults merged with .idx.yml).
  • Prints the value as a plain string to stdout.
  • Returns an error for unrecognized keys and lists all valid keys in the error message.

Output — idx config show

When .idx.yml exists:

  Config  /home/user/my-project/.idx.yml

  search.format         json     ← .idx.yml   (default: text)
  search.limit          0        · default
  search.operator       AND      · default
  search.context        0        · default
  search.relaxation              · default
  search.cache_ttl      1m0s     · default
  search.max_workers    4        · default
  watch.debounce        750ms    · default
  index.ignore          []       · default
  bm25.k1               1.5      · default
  bm25.b                0.75     · default
  bm25.proximity_weight 3        · default
  log.level             error    · default
  • Keys set in .idx.yml: rendered bold indigo with source ← .idx.yml (default: <value>).
  • Keys at built-in defaults: muted with source · default.

When no .idx.yml exists:

  No .idx.yml found — using built-in defaults.
  Tip: create .idx.yml at the project root to customize defaults.

Output — idx config get <key>

$ idx config get search.operator
AND

$ idx config get bm25.k1
1.5

Errors

  • get with unknown key: unknown config key "<key>" — valid keys: search.format, search.limit, ...

Reference — All Configurable Keys

Key Type Default Notes
search.format string text text or json
search.limit int 0 0 = unlimited; maps to --limit/-n
search.operator string AND AND or OR
search.context int 0 Context lines around matches
search.relaxation string "" Format >N; activates AND relaxation
search.cache_ttl duration 1m BM25 result cache TTL (e.g. 30s, 5m)
search.max_workers int 4 Parallel index-load workers
watch.debounce duration 750ms Debounce window for file events
index.ignore list [] Glob patterns to exclude from indexing
bm25.k1 float 1.5 BM25 term-frequency saturation
bm25.b float 0.75 BM25 document-length normalization
bm25.proximity_weight float 3.0 BM25 proximity bonus weight
bm25.popularity_weight float 0.3 Read-popularity boost weight; 0 disables; maps to --popularity-weight
log.level string error debug, info, warn, error

.idx.yml Format

# .idx.yml — place at the Git project root
search:
  format: json        # text | json
  limit: 20           # 0 = unlimited (was: size, still accepted for backward compat)
  operator: AND       # AND | OR
  context: 0
  relaxation: ""      # "" = off | ">3" = relax when >3 terms
  cache_ttl: 1m
  max_workers: 4

watch:
  debounce: 750ms

index:
  ignore:
    - vendor/
    - "*.pb.go"

bm25:
  k1: 1.5
  b: 0.75
  proximity_weight: 3.0
  popularity_weight: 0.3  # 0 = disabled

log:
  level: error        # debug | info | warn | error

Notes:

  • Duration values must be strings (e.g. 250ms, 2m, 30s). Invalid durations fail at startup.
  • index.ignore values are glob patterns matched against relative paths from the project root.
  • log.level is also overridable via the IDX_LOG_LEVEL environment variable; env takes precedence over .idx.yml.
  • Only project-level config is supported. There is no global ~/.idx/config.yml.
  • Migration note: the key search.size was renamed to search.limit. Old .idx.yml files using search.size continue to work without changes, but new files should use search.limit.

Examples

# Show full resolved configuration
idx config show

# Read a single key
idx config get search.operator
idx config get search.limit
idx config get bm25.k1