Skip to content

y3owk1n/neru / .agents/skills/neru-add-cli-command

neru-add-cli-command

Verified

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

just build
./bin/neru <command> --help     # against a running daemon: ./bin/neru launch
just genman

Then the standard pre-commit gate from AGENTS.md.

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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall