# spf13/cobra architecture

> Architecture diagram of the GitHub repository spf13/cobra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spf13/cobra
- Repository: https://github.com/spf13/cobra

## Overview

Cobra is a Go library for building command-line applications. An application defines a command tree, arguments, and flags; invoking its command execution path resolves a command and runs its action. The library also validates argument and flag constraints, generates shell-completion support, and can produce command documentation. The graph emphasizes these user-facing capabilities. Source excerpts establish execution and completion behavior, while several README-listed capabilities have no sampled implementation excerpt, so their internal links are omitted.

Main entry points: [`completions.go`](https://github.com/spf13/cobra/blob/main/completions.go) (Completion Engine), [`command.go`](https://github.com/spf13/cobra/blob/main/command.go) (Command Tree), [`shell_completions.go`](https://github.com/spf13/cobra/blob/main/shell_completions.go) (Completion Annotations), [`args.go`](https://github.com/spf13/cobra/blob/main/args.go) (Argument Validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Command Runtime"]
  node_command_model["Command Tree<br/>[command.go]"]
  node_cobra_helpers["Runtime Helpers<br/>[cobra.go]"]
end

subgraph group_inputs["Input Rules"]
  node_arg_validation["Argument Validation<br/>[args.go]"]
  node_flag_groups["Flag Groups<br/>[flag_groups.go]"]
end

subgraph group_completion["Shell Completion"]
  node_completion_engine["Completion Engine<br/>[completions.go]"]
  node_shell_annotations["Completion Annotations"]
  node_bash_completion["Bash Completion"]
  node_bash_v2_completion["Bash Completion V2"]
  node_fish_completion["Fish Completion"]
  node_zsh_completion["Zsh Completion<br/>[zsh_completions.go]"]
  node_powershell_completion["PowerShell Completion"]
  node_active_help["Active Help<br/>[active_help.go]"]
end

subgraph group_docs["Documentation"]
  node_doc_generators["Command Doc Generators"]
end

node_cli_user(("CLI User"))
node_pflag["pflag Library"]

node_cli_user -->|"invokes"| node_command_model
node_command_model -.->|"validates arguments"| node_arg_validation
node_command_model -.->|"validates flag groups"| node_flag_groups
node_command_model -.->|"uses flags"| node_pflag
node_command_model -->|"serves completion"| node_completion_engine
node_completion_engine -.->|"generates script"| node_bash_completion
node_completion_engine -.->|"generates script"| node_bash_v2_completion
node_completion_engine -.->|"generates script"| node_fish_completion
node_completion_engine -.->|"generates script"| node_zsh_completion
node_completion_engine -.->|"generates script"| node_powershell_completion
node_completion_engine -.->|"supports help"| node_active_help
node_shell_annotations -->|"annotates flags"| node_pflag
node_cli_user -.->|"requests generated docs"| node_doc_generators

click node_command_model "https://github.com/spf13/cobra/blob/main/command.go"
click node_cobra_helpers "https://github.com/spf13/cobra/blob/main/cobra.go"
click node_arg_validation "https://github.com/spf13/cobra/blob/main/args.go"
click node_flag_groups "https://github.com/spf13/cobra/blob/main/flag_groups.go"
click node_completion_engine "https://github.com/spf13/cobra/blob/main/completions.go"
click node_shell_annotations "https://github.com/spf13/cobra/blob/main/shell_completions.go"
click node_bash_completion "https://github.com/spf13/cobra/blob/main/bash_completions.go"
click node_bash_v2_completion "https://github.com/spf13/cobra/blob/main/bash_completionsV2.go"
click node_fish_completion "https://github.com/spf13/cobra/blob/main/fish_completions.go"
click node_zsh_completion "https://github.com/spf13/cobra/blob/main/zsh_completions.go"
click node_powershell_completion "https://github.com/spf13/cobra/blob/main/powershell_completions.go"
click node_active_help "https://github.com/spf13/cobra/blob/main/active_help.go"
click node_doc_generators "https://github.com/spf13/cobra/tree/main/doc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command_model,node_cobra_helpers,node_cli_user toneBlue
class node_arg_validation,node_flag_groups toneAmber
class node_completion_engine,node_shell_annotations,node_bash_completion,node_bash_v2_completion,node_fish_completion,node_zsh_completion,node_powershell_completion,node_active_help toneMint
class node_doc_generators toneRose
class node_pflag toneIndigo
```

## Components

### Command Runtime

- [Command Tree](https://github.com/spf13/cobra/blob/main/command.go): `command.go`
- [Runtime Helpers](https://github.com/spf13/cobra/blob/main/cobra.go): `cobra.go`

### Input Rules

- [Argument Validation](https://github.com/spf13/cobra/blob/main/args.go): `args.go`
- [Flag Groups](https://github.com/spf13/cobra/blob/main/flag_groups.go): `flag_groups.go`

### Shell Completion

- [Completion Engine](https://github.com/spf13/cobra/blob/main/completions.go): `completions.go`
- [Completion Annotations](https://github.com/spf13/cobra/blob/main/shell_completions.go): `shell_completions.go`
- [Bash Completion](https://github.com/spf13/cobra/blob/main/bash_completions.go): `bash_completions.go`
- [Bash Completion V2](https://github.com/spf13/cobra/blob/main/bash_completionsV2.go): `bash_completionsV2.go`
- [Fish Completion](https://github.com/spf13/cobra/blob/main/fish_completions.go): `fish_completions.go`
- [Zsh Completion](https://github.com/spf13/cobra/blob/main/zsh_completions.go): `zsh_completions.go`
- [PowerShell Completion](https://github.com/spf13/cobra/blob/main/powershell_completions.go): `powershell_completions.go`
- [Active Help](https://github.com/spf13/cobra/blob/main/active_help.go): `active_help.go`

### Documentation

- [Command Doc Generators](https://github.com/spf13/cobra/tree/main/doc): `doc`

### Other components

- **CLI User**
- **pflag Library**

## Connections

- CLI User → Command Tree: invokes (evidence: `command.go`)
- Command Tree → Argument Validation: validates arguments
- Command Tree → Flag Groups: validates flag groups
- Command Tree → pflag Library: uses flags
- Command Tree → Completion Engine: serves completion (evidence: `completions.go`)
- Completion Engine → Bash Completion: generates script
- Completion Engine → Bash Completion V2: generates script
- Completion Engine → Fish Completion: generates script
- Completion Engine → Zsh Completion: generates script
- Completion Engine → PowerShell Completion: generates script
- Completion Engine → Active Help: supports help
- Completion Annotations → pflag Library: annotates flags (evidence: `shell_completions.go`)
- CLI User → Command Doc Generators: requests generated docs
