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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.7 KB |
| agents/openai.yaml | config | 298 B |
SKILL.md
View on GitHub---
name: neru-add-cli-command
description: "Add 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
1. **Cobra command** in `internal/cli/<name>.go`, registered in an `init()`
like its siblings. Mode-shaped commands (hints/grid/scroll variants) go
through `BuildModeCommand(ModeConfig{...})` in `command_builders.go` instead
of hand-rolling cobra. Look at `hints.go` first. Long help text follows the
house style: prose, then flag explanations, then an `Examples:` block.
2. **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 in `internal/cli/cliutil`.
3. **IPC handler** in `internal/app/ipcctrl`. Handlers register into
`Controller.Handlers` via the sub-controller for their family
(`lifecycle`, `modes`, `actions`, `info`, `overlay`, `scroll`, …). Extend
the matching `RegisterHandlers`, and don't add a case to the controller.
4. **The actual work** lives in `internal/app/services/*` or a mode, never in
the handler. Handlers parse, delegate, and shape the `ipc.Response`.
5. **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's `Short`/`Long`, not the output.
6. **Docs**: update `docs/reference/cli.md`. It is the single home for CLI reference
facts.
7. **IPC reference**: a new IPC command gets a row in the Commands table of
`docs/reference/ipc.md`. `internal/architecture/ipc_reference_test.go`
fails while the table and the commands the daemon answers differ.
8. **Schemas**: when a reply type changes, run `just genschema`.
`internal/architecture/ipc_schema_test.go` fails while
`schemas/ipc.schema.json` is 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.go` with port mocks from
`internal/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 (root `AGENTS.md`, "Hard rules").
## Verify
```bash
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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |