cli-command-add

Apply the ref-python-coding-practices skill (rule 15 covers click + @run_async + CliError discipline), the ref-documentation-roles skill (it defines docs/CLI.md's role as the exhaustive CLI reference), the ref-cli-help-standards skill (the help-content contract every command's HelpSpec — rendering both --help and the agents manifest — must satisfy), and the ref-output-serialization-conventions skill for the command's output payload (every OutputField's value vocabulary, casing, and known carve-outs). If the command wraps an MCP tool (any verb under session/system/table/catalog/pq/docs), also apply the ref-cli-tool-wrapping skill — it owns the shared _wrapping helpers, the five wrapper categories, the type-scoping rule, the path-flag locality rule, and the wraps_tool drift contract (step 2's wrapper note has the binding details).

Steps

1. Pick or create the noun group under src/deephaven_mcp/cli/_commands/.

   • The nouns, with the routing gloss you need to place a verb (run dhcli agents tree for the live tree — it emits summaries, not "which noun should host this"): daemon (lifecycle of the local daemon), tool (inspect / invoke MCP tools — the raw escape hatch), session / system / table / catalog / pq (runtime MCP-tool wrappers — apply ref-cli-tool-wrapping), docs (documentation Q&A — connects directly to the docs MCP server, no daemon), config (inspect, validate, and author the configuration tree — show/validate/get/keys/files/set/unset/edit/init plus session/system add/remove/list; the authoring and inspection verbs declare needs_runtime=False and operate on files directly, making config the principal recovery surface when the tree is broken or empty), context (the sticky default session/system/PQ id, persisted in <runtime_dir>/context.json), self (tool self-management, e.g. shell completion — verbs here declare needs_runtime=False when they must work without a config tree).
   • Not an add target: agents emits machine-readable metadata about the live click tree, not user actions; new commands appear there automatically.
   • Default to an existing noun: add a verb under an existing noun; create a new noun only for a genuinely new domain.
   • Ground the naming in prior art: apply ref-cli-design-prior-art when choosing a noun, verb, or flag name — follow the convention a comparable CLI already established, cite the tool and the specific behavior, and state the reason if you depart from it.
   • File layout: each top-level noun is exactly one module _commands/<noun>.py, holding its group, all its verbs, any sub-groups, and its private helpers — do not create per-verb files or noun packages.
   • Module naming: the file is named for its noun alone (session.py, context.py). self_cmd.py is the sole suffixed filename, because self shadows the conventional instance parameter — do not generalize that _cmd suffix to any other noun.
   • If you add a noun, update the cli/ entry in ref-project-reference in the same changeset — it maps the CLI package and goes stale silently otherwise.

2. Add the click command. Copy the decorator stack from the model verb tool_call in cli/_commands/tool.py: @<group>.command(name, help_spec=HelpSpec(...)) → click options/arguments → @click.pass_obj (or @click.pass_context) → @run_async → async def. Exception: a verb that performs no I/O (pure metadata / self-management — canonical implementations: the agents verbs in agents.py, self completion in self_cmd.py) stays a plain synchronous def with no @run_async; never wrap a synchronous body in async def. Compose the help as a HelpSpec from cli/_help.py per the ref-cli-help-standards Help-content contract, and define the output shape once as an OutputSpec constant passed as the spec's output= field (Output is single-source) — output_spec derives from it automatically.