feat(ragctl): consolidated control-plane CLI scaffold (Step 0.10) - #36
Merged
officialCodeWork merged 2 commits intoMay 23, 2026
Merged
Conversation
Add `packages/ragctl/` — a dedicated workspace member that exposes the
single `ragctl` command, replacing the embedded CLI inside `rag-config`.
Working command groups (carried over from earlier steps):
- `config validate` / `config diff` (Step 0.4)
- `traces` (Step 0.7)
- `eval run` / `eval show` (Step 0.8)
- `version` (Step 0.10)
Scaffold sub-apps that announce their target step and exit 0, so the
published command shape is stable from day one:
- `ingest` → Step 1.10
- `query` → Step 3.1
- `logs` → Step 5.6
- `tenant` → Step 6.1
- `plugin` → Step 1.1
- `secret` → Step 6.7
Shell completion is enabled via Typer's `--install-completion` and
`--show-completion` flags (bash/zsh/fish/PowerShell).
The `ragctl` entry point now lives in `rag-ragctl`'s pyproject.toml.
The old `rag_config.cli` module is removed; the only internal importer
(`tests/eval/test_cli.py`) is updated to `from ragctl.main import app`.
Side fixes:
- Add `py.typed` markers to `rag-config` and `rag-observability` so
downstream mypy can resolve their types.
- Extend the Typer-friendly `B008` per-file ignore to
`packages/ragctl/src/ragctl/main.py`.
Tests: 19 new ragctl tests (root smoke, scaffold parametrized over all 6
stubbed groups, completion wiring). Full suite: 499 passed, 1 skipped.
Documentation:
- `docs/reference/ragctl.md` — full command reference + internals
- `docs/guides/ragctl-quickstart.md` — operator quickstart
- `docs/README.md` — new reference/ and guides/ index sections
- `packages/ragctl/README.md` — package overview
Phase 0 closes: 13/13 steps complete. Next step: 1.1 — Storage backends.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Typer 0.25's Rich-formatted ``--help`` wraps long flag names like ``--install-completion`` across lines in headless CI (no tty → narrow width), so the substring assertions in test_completion.py failed on ubuntu-22.04 and macos-14 even though they passed locally. Replace the substring tests with structural checks on the underlying Click command's registered params. The completion flags either are or aren't on the command — that's the real contract we care about and it's resilient to Rich-formatting quirks. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
packages/ragctl/owns theragctlentry point.config validate/config diff(0.4),traces(0.7),eval run/eval show(0.8),version(0.10).ingest→ 1.10,query→ 3.1,logs→ 5.6,tenant→ 6.1,plugin→ 1.1,secret→ 6.7.--install-completion/--show-completionflags (bash, zsh, fish, PowerShell).rag_config.climodule is deleted; the single internal importer (tests/eval/test_cli.py) is updated. No backwards-compat shim — per the user's standing preference against compat shims.py.typedmarkers torag-configandrag-observabilityso downstream mypy can resolve their types; extend the Typer-friendlyB008ignore topackages/ragctl/src/ragctl/main.py.Phase 0 closes: 13 / 13 steps complete. Next: Phase 1 Step 1.1 — Storage backends.
Documentation
docs/reference/ragctl.md— full command reference (overview, usage, internals, extension points)docs/guides/ragctl-quickstart.md— 5-minute operator tourdocs/README.md— newreference/andguides/index sectionspackages/ragctl/README.md— package overviewTest plan
uv run pytest -x -q— 499 passed, 1 skipped (19 new ragctl tests)uv run ruff check .— cleanuv run ruff format --check .— cleanuv run mypy packages/ apps/gateway/— 67 source files, no issuesubuntu-22.04,macos-14,windows-latestuv run ragctl --helpshows all 10 sub-command groupsuv run ragctl versionprintsragctl 0.1.0Notes
A separate task chip has been spawned to fix a pre-existing RAG001 false positive on
packages/core/src/rag_core/audit.py— not caused by this PR.