Go CLI Application Architecture
Organize around dependency direction and testable behavior, not a copied folder
template. Keep CLI framework code as an adapter around application services.
Core Workflow
- Identify commands, domain actions, external effects, and shared policies.
- Separate parsing/rendering from application orchestration and adapters.
- Define interfaces at the consumer that needs substitution.
- Construct dependencies once in a composition root and pass them explicitly.
- Keep configuration immutable after validation; give mutable state a dedicated store.
- Record ownership and cleanup for every acquired resource and background task.
- Test inward from pure logic to adapters and one assembled executable path.
Read Next
| Task |
Load |
| Design or refactor boundaries |
guidelines.md, workflows/design-application-boundaries.md |
| Review ownership and cleanup |
workflows/review-resource-lifecycle.md |
| Decide package and interface placement |
references/application-architecture/rules.md |
| Review patterns and examples |
references/application-architecture/examples.md |
| Understand dependency direction |
references/application-architecture/knowledge.md |
Guardrails
- Do not put domain behavior in Cobra
Run functions.
- Avoid a central interfaces package and broad catch-all service abstractions.
- Do not use package globals or
init for dependency construction.
- Keep fallible I/O and order-dependent startup out of
init; use explicit composition.
- Keep runtime configuration distinct from mutable application storage.
- Add layers only when they create a real seam, invariant, or dependency boundary.
Source Notes
Guidance is transformed and paraphrased from Marian Montagnino,
Building Modern CLI Applications in Go (Packt, 2023), especially Chapters
2-3, with original adaptations aligned to current Go conventions.
Concrete-first interfaces, dependency ownership, and adapter lifecycle guidance
also incorporates transformed material from Inanc Gumus, Go by Example:
Programmer's Guide to Idiomatic and Testable Programs (Manning, 2025),
Chapters 5 and 8-10.
Initialization and lifecycle guidance also incorporates transformed material
from Teiva Harsanyi, 100 Go Mistakes and How to Avoid Them (Manning, 2022),
Chapters 2, 6, 7, and 10.
1---2name: go-cli-application-architecture3description: Design and review maintainable Go CLI application boundaries, package layout, dependency direction, command factories, configuration ownership, adapters, services, storage, and composition roots. Use when starting a multi-command CLI, extracting business logic from Cobra, untangling globals, adding external dependencies, or deciding what belongs under cmd, internal, or reusable packages.4license: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 version: "0.3.0"8 displayName: Go CLI Application Architecture9 category: Go10 tags: go,golang,cli,architecture,packages,dependency-injection11---1213# Go CLI Application Architecture1415Organize around dependency direction and testable behavior, not a copied folder16template. Keep CLI framework code as an adapter around application services.1718## Core Workflow19201. Identify commands, domain actions, external effects, and shared policies.212. Separate parsing/rendering from application orchestration and adapters.223. Define interfaces at the consumer that needs substitution.234. Construct dependencies once in a composition root and pass them explicitly.245. Keep configuration immutable after validation; give mutable state a dedicated store.256. Record ownership and cleanup for every acquired resource and background task.267. Test inward from pure logic to adapters and one assembled executable path.2728## Read Next2930| Task | Load |31|---|---|32| Design or refactor boundaries | `guidelines.md`, `workflows/design-application-boundaries.md` |33| Review ownership and cleanup | `workflows/review-resource-lifecycle.md` |34| Decide package and interface placement | `references/application-architecture/rules.md` |35| Review patterns and examples | `references/application-architecture/examples.md` |36| Understand dependency direction | `references/application-architecture/knowledge.md` |3738## Guardrails3940- Do not put domain behavior in Cobra `Run` functions.41- Avoid a central interfaces package and broad catch-all service abstractions.42- Do not use package globals or `init` for dependency construction.43- Keep fallible I/O and order-dependent startup out of `init`; use explicit composition.44- Keep runtime configuration distinct from mutable application storage.45- Add layers only when they create a real seam, invariant, or dependency boundary.4647## Source Notes4849Guidance is transformed and paraphrased from Marian Montagnino,50*Building Modern CLI Applications in Go* (Packt, 2023), especially Chapters512-3, with original adaptations aligned to current Go conventions.5253Concrete-first interfaces, dependency ownership, and adapter lifecycle guidance54also incorporates transformed material from Inanc Gumus, *Go by Example:55Programmer's Guide to Idiomatic and Testable Programs* (Manning, 2025),56Chapters 5 and 8-10.5758Initialization and lifecycle guidance also incorporates transformed material59from Teiva Harsanyi, *100 Go Mistakes and How to Avoid Them* (Manning, 2022),60Chapters 2, 6, 7, and 10.
LVTD-LLC