Capability: cli
The
the-loopPython CLI companion — lightweight, one-dependency, extensible quality-of-life commands the plugin (and users) can call.
What it is
A Python package (cli/, import package the_loop, console script the-loop) with an extensible command registry. Python is deliberate: it leaves room for future self-learning/ML capabilities.
Current behaviour
- The CLI SHALL register commands via an extensible registry (
the_loop.commands). - The CLI SHALL have exactly one runtime dependency,
pyyaml>=6, and be stdlib otherwise. PyYAML is REQUIRED, not an extra: the CLI config, the harness config and every default the daemons read are YAML, so a missing parser used to degrade each read to empty, with the cause logged atdebugor not at all — leavingpollto exit with "no polling sources configured" against a file that listed sources (issue-97, decision-038). The[config]extra that once carried it SHALL be retained as an empty, deprecated no-op so pinned install lines keep resolving. the-loop --versionSHALL report the installed package version, derived from package metadata (importlib.metadata.version("the-loopy-one")) rather than a hardcoded string, so it always tracks the actually-installed release (issue-78).the-loop gh-webhook start|stopSHALL run/stop the HMAC-verified GitHub webhook receiver (see webhook-triggers).the-loop sessions register|list|closeSHALL manage the work-item ↔ harness-session registry used for webhook routing.the-loop scenariosSHALL output the table of every Gherkin scenario covered by the integration tests (--format table|markdown|json; see testing-and-contracts).the-loop eventsSHALL query the structured JSONL event log of the CLI's own routing/dispatch/session decisions (see observability).- The package SHALL be installable from PyPI as
the-loopy-one(import packagethe_loopand thethe-loopscript unchanged; see release-publishing). gh-webhook/poll/sessions/eventsSHALL read their defaults from a CLI config (cli-config.yaml) independent of any repo's.the-loop/harness-config.yaml(the plugin config) — resolved via--config/-c, else$THE_LOOP_CLI_CONFIG, else./.the-loop/cli-config.yaml(repo-relative, so an operator can track it in a chosen repo), else~/.the-loop/cli-config.yaml, so the CLI is not tied to a single repo (cli/README.md, decision-032).
Design
cli/README.md · architecture § CLI companion
History
| Work item | What changed | Links |
|---|---|---|
| issue-97 | PyYAML promoted from the [config] extra to a required runtime dependency; the three silent ImportError fallbacks removed and the zero-runtime-dependency guarantee retired | spec, decision-038 |
| issue-82 | Plugin config renamed config.yaml → harness-config.yaml (scenarios reads the new name with a pre-rename fallback); CLI config gained operator-declared collaborators + daemon-side notifications event filters | decision-035 |
| issue-78 | --version derives from package metadata instead of a hardcoded string that had frozen at 0.1.0 | spec |
| issue-63 | Split the CLI daemon's config (webhooks/polling/eventLog) out of the per-repo plugin config into an independent, repo-agnostic CLI config | spec, decision-032 |
| issue-50 | Added the structured event log and the events query command | spec, decision-025 |
| issue-21 | Published to PyPI as the-loopy-one with automatic semantic releases | spec, decision-019 |
| issue-15 | Added sessions registry commands and webhook --route dispatch | spec, decision-016 |
| issue-11 | Added scenarios (queryable integration-test scenario table) | spec, decision-014 |
| issue-1 | Established the CLI skeleton and the gh-webhook receiver (v0) | spec, decision-005 |