Skip to content

ragctl-quickstart.md

Latest commit

 

History

History
104 lines (74 loc) · 2.7 KB

ragctl-quickstart.md

File metadata and controls

104 lines (74 loc) · 2.7 KB
Raw

ragctl quickstart

A five-minute tour of the control-plane CLI shipped in Step 0.10.

Install

ragctl is part of the AgentContextOS uv workspace. Once you've bootstrapped the repo, the command is on your PATH inside the workspace virtualenv:

task bootstrap            # one-time: uv sync + pnpm install + pre-commit
uv run ragctl --help

If you only want the binary outside the workspace (e.g. on an operator workstation), install the published package once it lands on PyPI:

pip install rag-ragctl
ragctl --help

Verify your rag.yaml

The most useful command on day one. Run it before applying a config change to any environment:

ragctl config validate ops/configs/dev.yaml
# VALID    ops/configs/dev.yaml
#   version=v1  env=dev  tenants=2
#   embedder=openai  llm=openai  vector_store=qdrant

--json is the form you want from CI or pre-deploy scripts:

ragctl config validate ops/configs/dev.yaml --json

To inspect what differs between two configs:

ragctl config diff ops/configs/dev.yaml ops/configs/prod.yaml

Run a golden-set evaluation

The eval harness ships with a 5-sample fixture so you can verify the pipeline end-to-end without setting up real backends:

ragctl eval run tests/eval/golden/ --top-k 10 --output eval-report.json
ragctl eval show eval-report.json --verbose

To enable RAGAS faithfulness scoring:

pip install 'rag-config[eval]'
ragctl eval run tests/eval/golden/ --ragas

Query traces

With the local dev stack running (task dev-full), Jaeger is available at http://localhost:16686:

ragctl traces                                # last 20 traces for rag-platform
ragctl traces --service gateway --limit 50

Set up shell completion

Pick whichever line matches your shell:

ragctl --install-completion       # auto-detect from $SHELL
ragctl --show-completion zsh > ~/.zfunc/_ragctl   # manual install for zsh

What's not there yet

The following groups are scaffolded — they accept --help, exit cleanly, and announce which build step delivers the real implementation:

Command Lands in
ragctl plugin Step 1.1
ragctl ingest Step 1.10
ragctl query Step 3.1
ragctl logs Step 5.6
ragctl tenant Step 6.1
ragctl secret Step 6.7

If you script against them today, your script will keep working — the exit code and command shape will not change when the real implementation lands.

See also