CLI Reference

All rag-params-finder commands and flags. The server must be running at SERVER_URL (default: http://localhost:8001) for commands that call the API.

💻 Commands

▶️ `run` — Submit and monitor an experiment

rag-params-finder run --config <path>

Submits the experiment config to the server, then optionally polls run progress in the terminal.

Flag	Default	Description
`--config`	required	Path to the YAML experiment config
`--detach`	off	Submit and exit immediately; check the dashboard for status
`--watch` / `--no-watch`	watch on	Poll the server until the experiment reaches a terminal status (omit with `--detach`)

Examples:

# Submit and watch progress in the terminal
rag-params-finder run --config configs/mongodb/example-local.yaml

# Submit and detach — open http://localhost:5374 to track status
rag-params-finder run --config configs/mongodb/example-local.yaml --detach

# Submit, print the submission summary, then exit without polling the server
rag-params-finder run --config configs/mongodb/example-local.yaml --no-watch

# Voyage AI experiment (requires VOYAGE_API_KEY in .env)
rag-params-finder run --config configs/mongodb/example-voyage.yaml

# SIE experiment (requires SIE warm for bge-m3/stella-v5/splade-v3 + SIE_ENABLED=true)
rag-params-finder run --config configs/mongodb/example-sie.yaml

When watching, the CLI renders a live Rich table showing each run's current phase:

Run ID       | Model             | Method    | Size | Overlap | Phase
abc123-run-0 | all-MiniLM-L6-v2  | recursive | 512  | 50      | EMBEDDING
abc123-run-1 | all-MiniLM-L6-v2  | recursive | 512  | 0       | CHUNKING

Preflight: submission fails immediately with a clear error if required search indexes are missing (HTTP 422).

MongoDB: Atlas Search indexes / M0 quota — see Troubleshooting → Search index preflight failed.
Postgres: catalog check for the vector extension plus HNSW/GIN indexes from schema.sql. Fix by re-running schema bootstrap (server start), then rag-params-finder indexes list. See Postgres Setup.

`cancel` — Request cancellation

rag-params-finder cancel <experiment-id>

Posts POST /experiments/{experiment_id}/cancel. A running experiment stops after the current run phase completes. Not applicable once the experiment is already in a terminal status.

`pause` — Pause a running sweep

rag-params-finder pause <experiment-id>

Posts POST /experiments/{experiment_id}/pause. The sweep stops after the current run's current phase completes — in-flight work is not discarded. Status becomes paused. Completed runs and their chunks/results are kept.

Use this to temporarily free API quota or stop a long sweep without losing progress. Resume later with resume.

`resume` — Continue a paused sweep

rag-params-finder resume <experiment-id>

Posts POST /experiments/{experiment_id}/resume. Re-queues the experiment in a background task and executes only parameter combinations that have not yet reached COMPLETE. Skips are determined from stored run_status records — no YAML trimming required.

Only works when experiment status is paused.

`delete` — Delete experiment and all associated data

rag-params-finder delete <experiment-id>
rag-params-finder delete <experiment-id> --force

Deletes an experiment and all its associated data:

Experiment metadata
Run statuses
Chunks (embeddings)
Query results

Flag	Default	Description
`--force` / `-f`	off	Skip confirmation prompt

⚠️ Warning: This is a permanent operation that cannot be undone. Running experiments cannot be deleted — pause or cancel first. Paused experiments can be deleted.

Examples:

# Delete with confirmation prompt
rag-params-finder delete abc123-def4-5678-90ab-cdefg1234567

# Delete without confirmation (use with caution!)
rag-params-finder delete abc123-def4-5678-90ab-cdefg1234567 --force

Use case: Free storage by removing old experiments. Atlas M0 has a 512MB limit (~40MB per 10k chunks of embeddings). On Postgres/Supabase, cascade delete frees the same experiment rows/chunks — same CLI.

`indexes` — Manage search indexes

Backend-aware:

`STORAGE_BACKEND`	`indexes list`	`indexes reset`
`mongodb`	Atlas Search indexes (known vs unknown)	Drop unknown / rebuild chunks indexes
`postgres`	Catalog: `vector` extension + HNSW/GIN present vs missing	Not applicable — restart server / schema bootstrap
`elasticsearch`	`GET /api/stores` mapping summary (`rpf-chunks`, HNSW fields)	Not applicable — Atlas-only
`redis`	`GET /api/stores` index summary (`rpf:chunks`, HNSW TAG/VECTOR fields)	Not applicable — use `FT.DROPINDEX` + server restart

`indexes list`

rag-params-finder indexes list

Mongo: Lists all Atlas Search indexes across every database on the cluster. Tags each index KNOWN (managed by this project) or UNKNOWN. Shows total count vs the M0 limit (3).

Postgres: Lists the vector extension and required chunks indexes (chunks_embedding_384_hnsw, chunks_embedding_1024_hnsw, chunks_text_search_gin) as PRESENT or MISSING.

Elasticsearch: Prints the active store's GET /api/stores index summary (index name, HNSW fields). It does not open the cluster catalog directly.

Redis: Prints the active store's GET /api/stores index summary (rpf:chunks HNSW fields, TAG filters). It does not open the FT catalog directly. Use redis-cli FT.INFO rpf:chunks for low-level index info.

`GET /api/stores`

Public catalog of registered vector stores: provider, whether it is active, example_config, can_host_run_state, UI labels, capabilities, and a static index summary. Connection strings and API keys are omitted. indexes list reads this endpoint.

`indexes reset`

rag-params-finder indexes reset                    # default: drop unknown only + ensure required
rag-params-finder indexes reset --unknown-only     # same as default
rag-params-finder indexes reset --all              # drop ALL indexes on chunks + recreate
rag-params-finder indexes reset --force            # skip confirmation prompt

Flag	Default	Description
`--unknown-only` / `--all`	`--unknown-only`	Drop only unknown indexes, or all indexes on `chunks` and recreate
`--force` / `-f`	off	Skip confirmation prompt

Examples:

# See what's consuming quota (Mongo) or missing from schema.sql (Postgres)
rag-params-finder indexes list

# Free a slot by removing stray indexes from other tools/projects (Mongo)
rag-params-finder indexes reset

# Nuclear option — rebuild all chunks search indexes (~1–2 min rebuild) (Mongo)
rag-params-finder indexes reset --all --force

Known Atlas index names: vector_index_384, vector_index_1024, vector_index_30522, text_search_index.

`recover` — Retry failed runs (planned, Slice 10)

Not implemented yet. When shipped, this command will re-execute only runs in FAILED (and optionally INTERRUPTED) phase for an existing experiment, scrubbing stale chunks / results for those run_ids and leaving COMPLETE runs untouched. Config comes from the stored experiment document — no YAML trimming required.

Spec and acceptance criteria: SLICE-10-RUN-RECOVERY.md.

`version` — Print package version

rag-params-finder version

Listing experiments without a CLI subcommand

There is no list or status Typer command. Use:

Dashboard at http://localhost:5374, or
GET /experiments and GET /experiments/{experiment_id} (interactive API docs), or
curl / any HTTP client against the same URLs.

🔌 API Endpoints

The server exposes a REST API at http://localhost:8001. Full interactive docs at http://localhost:8001/docs.

Operational note /healthz and /health are process/dependency liveness checks, not transaction-readiness checks. They can be green while specific data-plane calls still fail. Use a real endpoint check (GET /experiments) to confirm data-path readiness.

Operational checks (named flags)

HEALTH_LIVENESS_LOCAL: confirms process and dependency ping endpoints.
- curl -sS http://127.0.0.1:8001/health | jq
- Expected: 200 with the /healthz storage fields for the active backend plus sie and version — MongoDB: "storage_backend": "mongodb", "mongodb": "ok"; Postgres: "storage_backend": "postgres", "postgres": "ok"
READINESS_DATA_PLANE: confirms the data plane is usable.
- curl -sS http://127.0.0.1:8001/experiments
- Expected: controlled empty list ([]) or actual experiment payload, and a meaningful error on malformed usage.
RECOVERY_INTENT_EXPLICIT: records that any reset/recovery action is operator-authorized and non-accidental.
- Before running destructive local data reset, perform an explicit run-level confirmation and note in run notes/log.

Method	Path	Purpose
GET	`/api/stores`	Registered vector stores, active store, labels, and index summary. Secrets omitted
GET	`/healthz`	Liveness for both stores (Slice 49B). See `/healthz` response shape below. HTTP 503 when either store is unreachable
GET	`/health`	Extended health — storage fields from `/healthz` plus `sie` (`disabled` / `reachable` / `unreachable`) and `version`

`/healthz` response shape (Slice 49B — two-store)

Every key present before Slice 49B stays with the same meaning: ok, storage_backend (the run-state store, i.e. STORAGE_BACKEND), storage_mode (the vector store's four-value mode — matches the dashboard label), and the per-engine key (mongodb / postgres, including Mongo's "skipped" when MONGODB_ATLAS_CLOUD_URI / MONGODB_ATLAS_LOCAL_URI is unset). Added: vector_store_backend, run_state_mode, and stores: {vector: {...}, run_state: {...}} (each with provider, mode, ok, latency_ms, and remediation when down). A mode ending in -local also includes container and image: the Compose default container name and image pin. Cloud modes omit those two fields.

Single-store (e.g. local Postgres — vector and run-state are the same store):

{
  "ok": true,
  "storage_backend": "postgres",
  "storage_mode": "postgres-local",
  "postgres": "ok",
  "vector_store_backend": "postgres",
  "run_state_mode": "postgres-local",
  "stores": {
    "vector": {
      "provider": "postgres",
      "mode": "postgres-local",
      "ok": true,
      "latency_ms": 3,
      "container": "rag-params-finder-postgres-local",
      "image": "pgvector/pgvector:0.8.5-pg16"
    },
    "run_state": {
      "provider": "postgres",
      "mode": "postgres-local",
      "ok": true,
      "latency_ms": 3,
      "container": "rag-params-finder-postgres-local",
      "image": "pgvector/pgvector:0.8.5-pg16"
    }
  }
}

Split-store (vector store down — HTTP 503):

{
  "ok": false,
  "storage_backend": "postgres",
  "storage_mode": "elasticsearch-local",
  "postgres": "ok",
  "vector_store_backend": "elasticsearch",
  "run_state_mode": "postgres-local",
  "stores": {
    "vector": {
      "provider": "elasticsearch",
      "mode": "elasticsearch-local",
      "ok": false,
      "latency_ms": null,
      "remediation": "Check ELASTICSEARCH_CLOUD_URL / ./start-services.sh elasticsearch status",
      "container": "rag-params-finder-elasticsearch-local",
      "image": "docker.elastic.co/elasticsearch/elasticsearch:9.5.0"
    },
    "run_state": {
      "provider": "postgres",
      "mode": "postgres-local",
      "ok": true,
      "latency_ms": 4,
      "container": "rag-params-finder-postgres-local",
      "image": "pgvector/pgvector:0.8.5-pg16"
    }
  }
}

storage_mode follows the vector store (VECTOR_STORE_BACKEND, default STORAGE_BACKEND). Single-store values stay the four compounds from that backend plus the connection-string host: mongodb-local, mongodb-cloud, postgres-local, postgres-cloud. Atlas cloud is detected via *.mongodb.net; hosted Supabase via *.supabase.*. It is not the YAML database_provider field (see configuration.md). The split-store JSON above illustrates the added keys with the Elasticsearch vector store and an explicit STORAGE_BACKEND=postgres pair. Unset STORAGE_BACKEND pairs mongodb-local. Local cluster: ./start-services.sh --elasticsearch-local and ./start-services.sh elasticsearch status.

POST /experiments engine gate: if normalized database_provider ≠ VECTOR_STORE_BACKEND (default STORAGE_BACKEND), the API returns HTTP 422 with a Config engine mismatch remediation before search-index / SIE preflight. The message text still says server storage_backend=; that value is the active vector store. Catalog/index missing-object 422s are a separate message family (see troubleshooting). | POST | /api/v1/sweep | Tier 1 ranked SIE vs Voyage sweep over caller-supplied corpus (see sie-setup.md) | | GET | /api/v1/best-config | Best config from persisted Tier-1 sweep history for task=<topic> | | POST | /experiments | Submit an experiment sweep (422 if search-index preflight fails) | | GET | /experiments | List all experiments | | GET | /experiments/vector-db-stats | Cluster-grouped vector DB / storage stats for all experiments | | GET | /experiments/{id} | Get experiment details + run statuses | | GET | /experiments/{id}/db-stats | Per-experiment chunk counts, storage estimates, index names | | GET | /experiments/{id}/results | Get query results for an experiment | | GET | /experiments/{id}/explore | Get data for the Search Explorer screen | | POST | /experiments/{id}/cancel | Request cancellation while status is running | | POST | /experiments/{id}/pause | Pause after current phase; status → paused | | POST | /experiments/{id}/resume | Resume a paused sweep; skips completed parameter combos | | DELETE | /experiments/{id} | Delete experiment and all associated data (chunks, results, run statuses) | | POST | /experiments/{id}/recover | Retry failed / interrupted runs only (planned — Slice 10) | | GET | /runs/{id}/status | Get a single run's current phase |

👉 See Also

Getting Started — install, configure, and run your first experiment
Configuration Reference — all YAML fields and sweep expansion rules
Dashboard Guide — reading results in the browser UI
Troubleshooting — fixing common errors

Navigation Menu

Repository navigation

CLI Reference

💻 Commands

▶️ `run` — Submit and monitor an experiment

`cancel` — Request cancellation

`pause` — Pause a running sweep

`resume` — Continue a paused sweep

`delete` — Delete experiment and all associated data

`indexes` — Manage search indexes

`indexes list`

`GET /api/stores`

`indexes reset`

`recover` — Retry failed runs (planned, Slice 10)

`version` — Print package version

Listing experiments without a CLI subcommand

🔌 API Endpoints

Operational checks (named flags)

`/healthz` response shape (Slice 49B — two-store)

👉 See Also

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

💻 Commands

▶️ run — Submit and monitor an experiment

cancel — Request cancellation

pause — Pause a running sweep

resume — Continue a paused sweep

delete — Delete experiment and all associated data

indexes — Manage search indexes

indexes list

GET /api/stores

indexes reset

recover — Retry failed runs (planned, Slice 10)

version — Print package version

Listing experiments without a CLI subcommand

🔌 API Endpoints

Operational checks (named flags)

/healthz response shape (Slice 49B — two-store)

👉 See Also

▶️ `run` — Submit and monitor an experiment

`cancel` — Request cancellation

`pause` — Pause a running sweep

`resume` — Continue a paused sweep

`delete` — Delete experiment and all associated data

`indexes` — Manage search indexes

`indexes list`

`GET /api/stores`

`indexes reset`

`recover` — Retry failed runs (planned, Slice 10)

`version` — Print package version

`/healthz` response shape (Slice 49B — two-store)