cmd-builder
Guides adding and structuring Go command entrypoints under cmd/: when to create a new cmd, layout, wiring only (no business logic), and use of internal packages. Use when creating or refactoring code under cmd/, adding a new executable, or when the user asks about cmd or entrypoint structure.
SKILL.md
Full skill instructions
Cmd Builder Skill
Use this skill when creating or modifying command entrypoints under cmd/.
When to create a new cmd
- New executable (new binary, distinct from api/evaluator/importer/migrations) → new directory under
cmd/<name>/withmain.go. - Existing executable → add flags or wiring in that cmd; do not add a second main for the same concern.
- Shared orchestration or workflow → implement in
internal/and call from cmd; keep cmd thin.
Layout
- One entrypoint per directory:
cmd/<name>/main.go,package main. - Each cmd builds to a single binary; the directory name is the conventional binary name (e.g.
cmd/api→api). - All logic lives in internal/; cmd only parses flags/env, opens resources (DB, etc.), and calls internal packages.
What cmd does (and does not)
- Does: Parse flags (e.g.
internal/cli) or env (internal/env); create DB client (internal/db); wire and call internal packages; log and exit on startup failure (log.Fatalor zerolog). - Does not: Contain business logic, algorithms, or domain rules; those live in
internal/. If a cmd grows a large loop or workflow, consider moving it into aninternal/package so it can be tested and reused.
Existing cmd apps (use as reference)
| Cmd | Role |
|---|---|
cmd/api | Load env, create DB client, start HTTP router (internal/router). |
cmd/evaluator | Load env and CLI flags, create DB and cache, run evaluation workflow via internal/evaluator and internal/candidate_tree. |
cmd/importer | Load env, create DB and tarkov.dev client, run internal/importers and internal/models purge/import. |
cmd/migrations | Parse args, open DB, run goose migrations. |
Imports
- Cmd imports internal by module path:
tarkov-build-optimiser/internal/<pkg>. - Example:
import "tarkov-build-optimiser/internal/env". - internal/ must not import cmd/.
Checklist for a new cmd
- Create
cmd/<name>/main.gowithpackage mainand amain()that exits on error (e.g.log.Fatal). - Parse config: use
internal/envfor env vars and optionallyinternal/clifor flags. - Open resources (e.g.
internal/db); defer or otherwise ensure cleanup where appropriate. - Construct and call internal packages only; no business logic in main.
- If the workflow is more than a few calls, consider an orchestration function in
internal/and call it from main.
Boundaries to respect
- No business logic in cmd/ — cmd wires and invokes; all domain and workflow logic stays in
internal/. - One main per binary — one
cmd/<name>/main.goper distinct executable. - internal does not import cmd — dependency flow is cmd → internal only.