y3owk1n/neru / .agents/skills/neru-add-cli-command
neru-add-cli-command
VerifiedAdd a Neru CLI command or flag: cobra command in internal/cli, IPC handler in internal/app/ipcctrl, service/mode work behind it, man pages, and docs/reference/cli.md. Use when adding or changing user-facing commands, subcommands, or flags. Not for config.toml options.
Adding a CLI command to Neru
Neru is a daemon plus a thin CLI. Almost every command serializes an IPC
request to the running daemon over its per-user Unix socket or Windows named
pipe. A new command therefore touches three layers plus docs.
Skipping the IPC layer and calling app code directly from internal/cli is
wrong even when it compiles.
The chain
- Cobra command in
internal/cli/<name>.go, registered in aninit()like its siblings. Mode-shaped commands (hints/grid/scroll variants) go throughBuildModeCommand(ModeConfig{...})incommand_builders.goinstead of hand-rolling cobra. Look athints.gofirst. Long help text follows the house style: prose, then flag explanations, then anExamples:block. - IPC transport is already generic (
internal/adapter/ipc), so you only add an action string. Keep the wire shape in one place and reuse existing request helpers ininternal/cli/cliutil. - IPC handler in
internal/app/ipcctrl. Handlers register intoController.Handlersvia the sub-controller for their family (lifecycle,modes,actions,info,overlay,scroll, …). Extend the matchingRegisterHandlers, and don't add a case to the controller. - The actual work lives in
internal/app/services/*or a mode, never in the handler. Handlers parse, delegate, and shape theipc.Response. - Man pages: regenerate with
just genman(backed by./cmd/genman). Cobra metadata is the source, so if the man page reads wrong, fix the command'sShort/Long, not the output. - Docs: update
docs/reference/cli.md. It is the single home for CLI reference facts. - IPC reference: a new IPC command gets a row in the Commands table of
docs/reference/ipc.md.internal/architecture/ipc_reference_test.gofails while the table and the commands the daemon answers differ. - Schemas: when a reply type changes, run
just genschema.internal/architecture/ipc_schema_test.gofails whileschemas/ipc.schema.jsonis out of date.
Mode flags are different
A flag on a mode command (hints --action left_click) is not registered by
hand. It is one entry in the descriptor table in internal/domain/modecmd,
carrying its own parse, its own render, and the modes that accept it. That
entry is what offers the flag on the command line, what the daemon and the
config validator read it with, and what writes its row in the reference.
After adding, removing or re-wording one, run just genflagref to rewrite the
generated region of docs/reference/cli.md. An architecture test
(internal/architecture/mode_flag_contract_test.go) fails while a descriptor
is unregistered or missing from that region, and while a mode command offers a
flag the table never declared.
Tests
- Command wiring and flag parsing: follow the table-driven patterns in
internal/cli/cli_test.go/*_internal_test.go. - Handler behavior:
internal/app/ipcctrl/*_test.gowith port mocks frominternal/ports/mocks. Assert the response shape and that the right service call happened, not internals. - Anything platform-gated must degrade with
derrors.CodeNotSupported, and a contract test pins that (rootAGENTS.md, "Hard rules").
Verify
just build
./bin/neru <command> --help # against a running daemon: ./bin/neru launch
just genman
Then the standard pre-commit gate from AGENTS.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |