# Go CLI Application Architecture

> 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.

- Skill: `lvtd-llc/go-cli-application-architecture` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add lvtd-llc/go-cli-application-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lvtd-llc/go-cli-application-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: LVTD-LLC (https://skillmd.com/u/lvtd-llc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lvtd-llc/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.