go-cli-application-architecture

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

1. Identify commands, domain actions, external effects, and shared policies.
2. Separate parsing/rendering from application orchestration and adapters.
3. Define interfaces at the consumer that needs substitution.
4. Construct dependencies once in a composition root and pass them explicitly.
5. Keep configuration immutable after validation; give mutable state a dedicated store.
6. Record ownership and cleanup for every acquired resource and background task.
7. 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.