structcli

2024-02-12T00:00:00+00:00
Declare your CLI contract once in Go structs. structcli</code> turns it into flags, env vars, config-file loading, validation, organized help, and machine-readable contracts for agents.</p>

Less Cobra/Viper boilerplate</li>
Better CLIs for humans</li>
Better contracts for automation and LLMs</li>
Compiles to WASM out of the box</li>
</ul>
Stop writing plumbing. Start shipping commands.</p>
⚡ Quick Start§</a>
</h2>
Start with a plain Go struct:</p>
package</span> main</span></span>
</span>
import</span> (</span></span>
	"fmt"</span></span>
</span>
	"github.com/leodido/structcli"</span></span>
	"github.com/spf13/cobra"</span></span>
	"go.uber.org/zap/zapcore"</span></span>
)</span></span>
</span>
type</span> Options</span> struct</span> {</span></span>
	LogLevel</span> zapcore</span>.</span>Level</span></span>
	Port</span>     int</span></span>
}</span></span>
</span>
func</span> main</span>() {</span></span>
	opts</span> := &</span>Options</span>{}</span></span>
	cli</span> := &</span>cobra</span>.</span>Command</span>{</span></span>
		Use</span>:</span> "myapp"</span>,</span></span>
		RunE</span>:</span> func</span>(</span>c</span> *</span>cobra</span>.</span>Command</span>,</span> args</span> []</span>string</span>)</span> error</span> {</span></span>
			fmt</span>.</span>Println</span>(</span>opts</span>)</span> // already populated</span></span>
</span>
			return</span> nil</span></span>
		},</span></span>
	}</span></span>
</span>
	structcli</span>.</span>Bind</span>(</span>cli</span>,</span> opts</span>)</span></span>
	structcli</span>.</span>ExecuteOrExit</span>(</span>cli</span>)</span></span>
}</span></span></code></pre>
Bind</code> creates flags and env vars from your struct and registers it for auto-unmarshal. ExecuteOrExit</code> hydrates the struct from flags, env vars, config, and defaults before your RunE</code> fires.</p>
❯</span> go run examples/minimal/main.go</span> --help</span></span>
# Usage:</span></span>
#   myapp [flags]</span></span>
#</span></span>
# Flags:</span></span>
#   -h, --help                     help for myapp</span></span>
#       --loglevel zapcore.Level    {debug,info,warn,error,dpanic,panic,fatal} (default info)</span></span>
#       --port int</span></span></code></pre>
Add tags when you want aliases, env vars, shorthand, defaults, and descriptions:</p>
type</span> Options</span> struct</span> {</span></span>
	LogLevel</span> zapcore</span>.</span>Level</span> `flag:"level" flagdescr:"Set logging level" flagenv:"true"`</span></span>
	Port</span>     int</span>           `flagshort:"p" flagdescr:"Server port" flagenv:"true" default:"3000"`</span></span>
}</span></span></code></pre>❯</span> go run examples/simple/main.go</span> -h</span></span>
# A simple CLI example</span></span>
#</span></span>
# Usage:</span></span>
#   myapp [flags]</span></span>
#</span></span>
# Flags:</span></span>
#   -h, --help                  help for myapp</span></span>
#       --level zapcore.Level   Set logging level {debug,info,warn,error,dpanic,panic,fatal} (default info)</span></span>
#   -p, --port int              Server port (default 3000)</span></span>
#</span></span>
# Global Flags:</span></span>
#       --jsonschema string[="true"]   output JSON Schema and exit (bare: this command, =tree: full subtree)</span></span>
#       --mcp                          serve MCP over stdio</span></span></code></pre>❯</span> MYAPP_LOGLEVEL=debug go run examples/simple/main.go</span></span>
# &{debug 3000}</span></span></code></pre>❯</span> MYAPP_LOGLEVEL=error MYAPP_PORT=</span>9000</span> go run examples/simple/main.go</span> --level</span> dpanic</span></span>
# &{dpanic 9000}</span></span></code></pre>
Built-in types like zapcore.Level</code> are validated automatically too.</p>
Out of the box, your CLI supports:</p>

📝 Command-line flags (--level info</code>, -p 8080</code>)</li>
🌍 Environment variables (MYAPP_PORT=8080</code>)</li>
💦 Options precedence (flags > env vars > config file > defaults)</li>
✅ Automatic validation and type conversion</li>
📚 Beautiful help output with proper grouping</li>
</ul>
Add the AI-native wiring below and it also gains machine-readable JSON Schema, structured JSON errors, semantic exit codes, and optional MCP tool-server mode for agents.</p>
Build AI-Native CLIs§</a>
</h2>
structcli</code> does not just generate flags for humans. It can make your CLI legible to agents too.</p>
Instead of scraping --help</code> and guessing, an agent can discover the contract, call the command correctly, and recover from structured failures.</p>
structcli</span>.</span>Setup</span>(</span>rootCmd</span>,</span></span>
    structcli</span>.</span>WithJSONSchema</span>(),</span></span>
    structcli</span>.</span>WithHelpTopics</span>(</span>helptopics</span>.</span>Options</span>{</span>ReferenceSection</span>:</span> true</span>}),</span>  // "mycli env-vars" and "mycli config-keys"</span></span>
    structcli</span>.</span>WithFlagErrors</span>(),</span>  // Optional, but recommended for typed flag-parse errors</span></span>
    structcli</span>.</span>WithMCP</span>(),</span>         // Optional, exposes the CLI as an MCP server over stdio</span></span>
)</span></span>
structcli</span>.</span>ExecuteOrExit</span>(</span>rootCmd</span>)</span></span></code></pre>
With that wiring:</p>

--jsonschema</code> exposes flags, defaults, required inputs, enums, and env bindings for the current command; --jsonschema=tree</code> dumps the entire subtree in one call</li>
mycli env-vars</code> and mycli config-keys</code> list every environment variable binding and config file key across the command tree</li>
HandleError</code> / ExecuteOrExit</code> emit structured JSON errors instead of forcing callers to parse human-oriented output</li>
--mcp</code> exposes the same command tree as MCP tools over stdio, with typed inputs and structured tool-call failures</li>
semantic exit codes tell the caller whether it should fix input, fix config, retry, or escalate to a human</li>
</ul>
The same contract spans flags, env vars, config, validation, and enum constraints.</p>
$</span> mycli srv</span> --jsonschema</span></span>
{</span></span>
  "properties":</span> {</span></span>
    "port":</span> {</span></span>
      "type":</span> "integer",</span></span>
      "default":</span> 3000,</span></span>
      "x-structcli-env-vars":</span> [</span>"MYCLI_SRV_PORT"</span>]</span></span>
    },</span></span>
    "secret-key":</span> {</span></span>
      "type":</span> "string",</span></span>
      "x-structcli-env-vars":</span> [</span>"MYCLI_SRV_SECRET_KEY"</span>],</span></span>
      "x-structcli-env-only":</span> true</span></span>
    }</span></span>
  },</span></span>
  "x-structcli-config-flag":</span> "config"</span></span>
}</span></span></code></pre>
Use --jsonschema=tree</code> to dump the entire command subtree in a single call: no need to invoke each subcommand separately:</p>
$</span> mycli</span> --jsonschema=tree</span>   # JSON array of schemas for all commands</span></span>
$</span> mycli srv</span> --jsonschema=tree</span>  # schemas for srv + its subcommands</span></span></code></pre>
No --help</code> parsing. No guessing what failed. Just a CLI that can explain itself and fail in machine-actionable ways.</p>
Use exitcode.Category(code)</code> and exitcode.IsRetryable(code)</code> to decide what to do next. See jsonschema.WithEnumInDescription()</code> for schema customization, and pass schema options through WithJSONSchema</code> with jsonschema.Options{SchemaOpts: ...}</code>.</p>
For CLIs that capture output streams during command construction, configure mcp.Options.CommandFactory</code> so each MCP tool call builds a fresh command with the tool-call stdout and stderr writers. This keeps MCP protocol output separate from command output while preserving the existing command tree schema. If the command constructor requires stdin, the factory can wire a non-interactive reader such as strings.NewReader("")</code>.</p>
For build-time discovery, generate.WriteAll</code> produces SKILL.md, llms.txt, and AGENTS.md from the same struct definitions: wire it into //go:generate</code> and the files stay in sync automatically.</p>
Read the full AI-native guide</a> or walk through the runnable structured error example</a>.</p>
⬇️ Install§</a>
</h2>
go</span> get github.com/leodido/structcli</span></span></code></pre>📦 Key Features§</a>
</h2>
🧩 Declarative Flags Definition§</a>
</h3>
Define flags once using Go struct tags.</p>
No more boilerplate for Flags().StringVarP</code>, Flags().IntVar</code>, viper.BindPFlag</code>, etc.</p>
Yes, you can nest</em> structs too.</p>
type</span> ServerOptions</span> struct</span> {</span></span>
	// Basic flags</span></span>
	Host</span> string</span> `flag:"host" flagdescr:"Server host" default:"localhost"`</span></span>
	Port</span> int</span>    `flagshort:"p" flagdescr:"Server port" flagrequired:"true" flagenv:"true"`</span></span>
</span>
	// Environment variable binding</span></span>
	APIKey</span> string</span> `flagenv:"true" flagdescr:"API authentication key"`</span></span>
</span>
	// Network contracts using net families</span></span>
	BindIP</span>        net</span>.</span>IP</span>     `flag:"bind-ip" flaggroup:"Network" flagdescr:"Bind interface IP" flagenv:"true"`</span></span>
	BindMask</span>      net</span>.</span>IPMask</span> `flag:"bind-mask" flaggroup:"Network" flagdescr:"Bind interface mask" flagenv:"true"`</span></span>
	AdvertiseCIDR</span> net</span>.</span>IPNet</span>  `flag:"advertise-cidr" flaggroup:"Network" flagdescr:"Advertised service subnet (CIDR)" flagenv:"true"`</span></span>
	TrustedPeers</span>  []</span>net</span>.</span>IP</span>   `flag:"trusted-peers" flaggroup:"Network" flagdescr:"Trusted peer IPs (comma separated)" flagenv:"true"`</span></span>
</span>
	// Flag grouping for organized help</span></span>
	LogLevel</span> zapcore</span>.</span>Level</span> `flag:"log-level" flaggroup:"Logging" flagdescr:"Set log level"`</span></span>
	LogFile</span>  string</span>        `flag:"log-file" flaggroup:"Logging" flagdescr:"Log file path" flagenv:"true"`</span></span>
</span>
	// Nested structs for organization</span></span>
	Database</span> DatabaseConfig</span> `flaggroup:"Database"`</span></span>
</span>
	// Enum type (registered via RegisterEnum)</span></span>
	TargetEnv</span> Environment</span> `flag:"target-env" flagdescr:"Set the target environment" default:"dev"`</span></span>
}</span></span>
</span>
type</span> DatabaseConfig</span> struct</span> {</span></span>
	URL</span>      string</span> `flag:"db-url" flagdescr:"Database connection URL"`</span></span>
	MaxConns</span> int</span>    `flagdescr:"Max database connections" default:"10" flagenv:"true"`</span></span>
}</span></span></code></pre>
See full example</a> for more details.</p>
🛠️ Automatic Environment Variable Binding§</a>
</h3>
Automatically generate environment variables binding them to configuration files (YAML, JSON, TOML, etc.) and flags.</p>
From the previous options struct, you get the following env vars automatically:</p>

FULL_SRV_PORT</code></li>
FULL_SRV_APIKEY</code></li>
FULL_SRV_BIND_IP</code></li>
FULL_SRV_BIND_MASK</code></li>
FULL_SRV_ADVERTISE_CIDR</code></li>
FULL_SRV_TRUSTED_PEERS</code></li>
FULL_SRV_DATABASE_MAXCONNS</code></li>
FULL_SRV_LOGFILE</code>, FULL_SRV_LOG_FILE</code></li>
</ul>
Every struct field with the flagenv:"true"</code> tag gets an environment variable (two if the struct field also has the flag:"..."</code> tag, see struct field LogFile</code>).
Use flagenv:"only"</code> for fields that should be settable exclusively via environment variable or config file: CLI usage (--flag=value</code>) is rejected at runtime.</p>
The prefix of the environment variable name is the CLI name plus the command name to which those options are attached to.</p>
Environment variables are command-scoped for command-local options.
For example, if Port</code> is attached to the srv</code> command, FULL_SRV_PORT</code> is used (not FULL_PORT</code>).</p>
⚙️ Configuration File Support§</a>
</h3>
Set up configuration file discovery (flag, environment variable, and fallback paths) via Setup</code>:</p>
structcli</span>.</span>Setup</span>(</span>rootCmd</span>,</span></span>
    structcli</span>.</span>WithAppName</span>(</span>"full"</span>),</span></span>
    structcli</span>.</span>WithConfig</span>(</span>config</span>.</span>Options</span>{}),</span></span>
)</span></span></code></pre>
Enable strict config-key validation with:</p>
structcli</span>.</span>Setup</span>(</span>rootCmd</span>,</span></span>
    structcli</span>.</span>WithAppName</span>(</span>"full"</span>),</span></span>
    structcli</span>.</span>WithConfig</span>(</span>config</span>.</span>Options</span>{</span>ValidateKeys</span>:</span> true</span>}),</span></span>
)</span></span></code></pre>
When enabled, Unmarshal</code> fails if command-relevant config contains unknown keys.</p>
WithAppName</code> sets the env prefix. WithConfig</code> registers the --config</code> flag and defers config loading to ExecuteC</code>'s bind pipeline (before auto-unmarshal). Ordering between Setup</code> and Bind</code> does not matter: WithAppName</code> retroactively patches env annotations on already-defined flags.</p>
Individual SetupConfig</code>, SetupDebug</code>, etc. remain available for power users who need fine-grained control.</p>
The line above:</p>

creates --config</code> global flag</li>
creates FULL_CONFIG</code> env var</li>
sets /etc/full/</code>, $HOME/.full/</code>, $PWD/.full/</code> as fallback paths for config.yaml</code></li>
</ul>
Magic, isn't it?</p>
What's left? Tell your CLI to load the configuration file (if any).</p>
rootC</span>.</span>PersistentPreRunE</span> =</span> func</span>(</span>c</span> *</span>cobra</span>.</span>Command</span>,</span> args</span> []</span>string</span>)</span> error</span> {</span></span>
	_</span>,</span> configMessage</span>,</span> configErr</span> :=</span> structcli</span>.</span>UseConfigSimple</span>(</span>c</span>)</span></span>
	if</span> configErr</span> !=</span> nil</span> {</span></span>
		return</span> configErr</span></span>
	}</span></span>
	if</span> configMessage</span> !=</span> ""</span> {</span></span>
		c</span>.</span>Println</span>(</span>configMessage</span>)</span></span>
	}</span></span>
</span>
	return</span> nil</span></span>
}</span></span></code></pre>
UseConfigSimple(c)</code> loads config into the root config scope and merges only the relevant section into c</code>'s effective scope.</p>
🧠 Viper Model Scopes§</a>
</h4>
structcli</code> uses two different viper scopes on purpose:</p>

structcli.GetConfigViper(rootOrLeafCmd)</code> -> root-scoped config source</strong> (config file data tree)</li>
structcli.GetViper(cmd)</code> -> command-scoped effective values</strong> (flags/env/defaults + command-relevant config)</li>
</ul>
This separation keeps config-file loading isolated from runtime command state.</p>
If you need imperative values in tests or application code, write to the right scope:</p>
// 1) Effective override for one command context</span></span>
structcli</span>.</span>GetViper</span>(</span>cmd</span>).</span>Set</span>(</span>"timeout"</span>,</span> 60</span>)</span></span>
</span>
// 2) Config-tree style injection (top-level + command section)</span></span>
structcli</span>.</span>GetConfigViper</span>(</span>rootCmd</span>).</span>Set</span>(</span>"srv"</span>,</span> map</span>[</span>string</span>]</span>any</span>{</span></span>
  "port"</span>:</span> 8443</span>,</span></span>
})</span></span></code></pre>
Global viper.Set(...)</code> is not used by structcli.Unmarshal(...)</code> resolution.
Use GetViper</code>/GetConfigViper</code> instead.</p>
📜 Configuration Is First-Class Citizen§</a>
</h4>
Configuration can mirror your command hierarchy.</p>
Settings can be global (at the top level) or specific to a command or subcommand. The most specific section always takes precedence.</p>
# Global settings apply to all commands unless overridden by a specific section.</span></span>
# `dryrun` matches the `DryRun` struct field name.</span></span>
dryrun</span>:</span> true</span></span>
verbose</span>:</span> 1</span> # A default verbosity level for all commands.</span></span>
</span>
# Config for the `srv` command (`full srv`)</span></span>
srv</span>:</span></span>
  # `port` matches the `Port` field name.</span></span>
  port</span>:</span> 8433</span></span>
  # Network options</span></span>
  bind-ip</span>:</span> "10.20.0.10"</span></span>
  bind-mask</span>:</span> "ffffff00"</span></span>
  advertise-cidr</span>:</span> "10.20.0.0/24"</span></span>
  trusted-peers</span>:</span> "10.20.0.11,10.20.0.12"</span></span>
  # `log-level` matches the `flag:"log-level"` tag.</span></span>
  log-level</span>:</span> "warn"</span></span>
  # `logfile` matches the `LogFile` field name.</span></span>
  logfile</span>:</span> /var/log/mysrv.log</span></span>
</span>
  # Flattened keys can set options in nested structs.</span></span>
  # `db-url` (from `flag:"db-url"` tag) maps to ServerOptions.Database.URL.</span></span>
  db-url</span>:</span> "postgres://user:pass@db/prod"</span></span>
</span>
  # Nested keys are also supported.</span></span>
  database</span>:</span></span>
    # Struct field key style</span></span>
    url</span>:</span> "postgres://user:pass@db/prod"</span></span>
    # Alias key style (from `flag:"db-url"`)</span></span>
    db-url</span>:</span> "postgres://user:pass@db/prod"</span></span>
</span>
# Config for the `usr` command group.</span></span>
usr</span>:</span></span>
  # This nested section matches the `usr add` command (`full usr add`).</span></span>
  # Its settings are ONLY applied to 'usr add'.</span></span>
  add</span>:</span></span>
    name</span>:</span> "Config User"</span></span>
    email</span>:</span> "config.user@example.com"</span></span>
    age</span>:</span> 42</span></span>
    # Command specific override</span></span>
    dry</span>:</span> false</span></span>
# NOTE: Per the library's design, there is no other fallback other than from the top-level.</span></span>
# A command like 'usr delete' would ONLY use the global keys above (if those keys/flags are attached to it),</span></span>
# as an exact 'usr.delete' section is not defined.</span></span></code></pre>
This configuration system supports:</p>

Hierarchical Structure</strong>: Nest keys to match your command path (e.g., usr: { add: { ... } }</code>).</li>
Strict Precedence</strong>: Only settings from the global scope and the exact command path section are merged. There is no automatic fallback to parent command sections.</li>
Flexible Keys</strong>: You can use struct field names and aliases (flag:"..."</code>) in both flattened and nested forms.</li>
Supported Forms for Nested Fields</strong>: db-url</code>, database.url</code>, database: { url: ... }</code>, and database: { db-url: ... }</code>.</li>
</ul>
✅ Built-in Validation & Transformation§</a>
</h3>
Supports validation, transformation, and custom flag type definitions through simple interfaces.</p>
Your struct must implement Options</code> (via Attach</code>) and can optionally implement ValidatableOptions</code> and TransformableOptions</code>.</p>
type</span> UserConfig</span> struct</span> {</span></span>
	Email</span> string</span> `flag:"email" flagdescr:"User email" validate:"email"`</span></span>
	Age</span>   int</span>    `flag:"age" flagdescr:"User age" validate:"min=18,max=120"`</span></span>
	Name</span>  string</span> `flag:"name" flagdescr:"User name" mod:"trim,title"`</span></span>
}</span></span>
</span>
func</span> (</span>o </span>*</span>ServerOptions</span>)</span> Validate</span>(</span>ctx</span> context</span>.</span>Context</span>) []</span>error</span> {</span></span>
    // Automatic validation</span></span>
}</span></span>
</span>
func</span> (</span>o </span>*</span>ServerOptions</span>)</span> Transform</span>(</span>ctx</span> context</span>.</span>Context</span>)</span> error</span> {</span></span>
    // Automatic transformation</span></span>
}</span></span></code></pre>
See a full working example here</a>.</p>
🚧 Automatic Debugging Support§</a>
</h3>
Create a --debug-options</code> flag (plus a matching env var) for troubleshooting config/env/flags resolution.</p>
structcli</span>.</span>Setup</span>(</span>rootCmd</span>,</span> structcli</span>.</span>WithDebug</span>(</span>debug</span>.</span>Options</span>{}))</span></span></code></pre>
Or standalone: structcli.SetupDebug(rootCmd, debug.Options{})</code>.</p>
The flag accepts text</code> (default when used bare) or json</code> for machine-readable output. Truthy values like true</code>, 1</code>, yes</code> are treated as text</code> for backward compatibility.</p>
Text output</strong>: an aligned table showing each flag's resolved value and where it came from:</p>
❯</span> go run examples/full/main.go srv</span> --debug-options --config</span> examples/full/config.yaml</span> -p</span> 3333</span></span>
# ...</span></span>
# Command: full srv</span></span>
#</span></span>
# Flags:</span></span>
#   --apikey                 secret-api-key                       (default)</span></span>
#   --config                 examples/full/config.yaml            (flag)</span></span>
#   --database.maxconns      3                                    (default)</span></span>
#   --db-url                 postgres://user:pass@localhost/mydb  (default)</span></span>
#   --debug-options          text                                 (flag)</span></span>
#   --host                   production-server                    (default)</span></span>
#   --log-file               /var/log/mysrv.log                   (default)</span></span>
#   --log-level              debug                                (default)</span></span>
#   --port                   3333                                 (flag)</span></span>
#   --target-env             dev                                  (default)</span></span>
#   ...</span></span>
#</span></span>
# Values:</span></span>
#   apikey: secret-api-key</span></span>
#   host: production-server</span></span>
#   log-level: debug</span></span>
#   port: 3333</span></span>
#   ...</span></span></code></pre>
JSON output</strong>: structured data for AI agents and tooling:</p>
❯</span> go run examples/full/main.go srv</span> --debug-options=json --config</span> examples/full/config.yaml</span> -p</span> 3333</span></span>
# ...</span></span>
# {</span></span>
#   "command": "full srv",</span></span>
#   "flags": [</span></span>
#     ...</span></span>
#     {"name": "config", "value": "examples/full/config.yaml", "default": "", "changed": true, "source": "flag"},</span></span>
#     {"name": "db-url", "value": "postgres://user:pass@localhost/mydb", "default": "", "changed": false, "source": "default"},</span></span>
#     {"name": "log-level", "value": "debug", "default": "info", "changed": false, "source": "default"},</span></span>
#     {"name": "port", "value": "3333", "default": "0", "changed": true, "source": "flag"},</span></span>
#     ...</span></span>
#   ],</span></span>
#   "values": {"apikey": "secret-api-key", "host": "production-server", "log-level": "debug", "port": 3333, ...}</span></span>
# }</span></span></code></pre>
Source attribution resolves each flag to flag</code> (CLI), env</code>, config</code>, or default</code>. For env-sourced flags, the text output includes the variable name (e.g., (env: MYAPP_LOG_LEVEL)</code>).</p>
The flag can also be activated via environment variable: FULL_DEBUG_OPTIONS=json</code>.</p>
📋 Self-Documenting Help Topics§</a>
</h3>
WithHelpTopics</code> (or standalone SetupHelpTopics</code>) adds two help topic commands that list every environment variable binding and every valid configuration file key across the command tree.</p>
structcli</span>.</span>Setup</span>(</span>rootCmd</span>,</span> structcli</span>.</span>WithHelpTopics</span>(</span>helptopics</span>.</span>Options</span>{}))</span></span></code></pre>
Call this after all subcommands and flags are defined (typically right before ExecuteOrExit</code>).</p>
By default the commands appear as regular subcommands under "Available Commands:". Set ReferenceSection: true</code> to move them into a dedicated "Reference:" section instead.</p>
Environment variable listing</strong>: mycli env-vars</code>:</p>
Environment Variables</span></span>
</span>
  mycli (global):</span></span>
    MYCLI_VERBOSE  --verbose  bool           false</span></span>
</span>
  mycli serve:</span></span>
    MYCLI_SERVE_HOST  --host  string         localhost</span></span>
    MYCLI_SERVE_PORT  --port  int            8080</span></span></code></pre>
Configuration key listing</strong>: mycli config-keys</code>:</p>
Configuration Keys</span></span>
</span>
  Config flag: --config</span></span>
  Supported formats: yaml, json, toml. Searches: $HOME/.mycli, /etc/mycli</span></span>
</span>
  mycli (global):</span></span>
    output   --output   string         text</span></span>
    verbose  --verbose  bool           false</span></span>
</span>
  mycli serve:</span></span>
    host      --host      string         localhost</span></span>
    port      --port      int            8080</span></span>
    tls-cert  --tls-cert  string         ""</span></span>
</span>
  Keys can be nested under the command name in the config file.</span></span></code></pre>
With ReferenceSection: true</code>, both topics appear under "Reference:" in --help</code> output instead of "Available Commands:". Flags marked flagenv:"only"</code> show an (env-only)</code> suffix in the env-vars listing and are excluded from config-keys (since they are hidden). Config keys derived from embedded struct field paths appear as aliases (e.g., database.maxconns</code> → alias for --database.maxconns</code>).</p>
For machine-readable cross-tree data, use --jsonschema=tree</code> instead: it provides the same information in structured JSON.</p>
↪️ Sharing Options Between Commands§</a>
</h3>
In complex CLIs, multiple commands often need access to the same global configuration and shared resources (like a logger or a database connection). structcli</code> provides a pattern using the ContextInjector</code></a> interface to achieve this without resorting to global variables, by propagating a single "source of truth" through the command context.</p>
The pattern allows you to:</p>

Populate a shared options struct once from flags, environment variables, or a config file.</li>
Initialize "computed state" (like a logger) based on those options.</li>
Share this single, fully-prepared "source of truth" with any subcommand that needs it.</li>
</ul>
🍩 In a Nutshell§</a>
</h4>
Create a shared struct that implements the ContextInjector</code> interface. This struct will hold both the configuration flags and the computed state (e.g., the logger).</p>
// This struct holds our shared state.</span></span>
type</span> CommonOptions</span> struct</span> {</span></span>
    LogLevel</span> zapcore</span>.</span>Level</span> `flag:"loglevel" flagdescr:"Logging level" default:"info"`</span></span>
    Logger</span>   *</span>zap</span>.</span>Logger</span>   `flagignore:"true"`</span> // This field is computed, not a flag.</span></span>
}</span></span>
</span>
// Context injects the struct into the command context during auto-unmarshal.</span></span>
func</span> (</span>o </span>*</span>CommonOptions</span>)</span> Context</span>(</span>ctx</span> context</span>.</span>Context</span>)</span> context</span>.</span>Context</span> {</span> /* ... */</span> }</span></span>
</span>
// FromContext retrieves the struct from context (user-side, not interface-enforced).</span></span>
func</span> (</span>o </span>*</span>CommonOptions</span>)</span> FromContext</span>(</span>ctx</span> context</span>.</span>Context</span>)</span> error</span> {</span> /* ... */</span> }</span></span>
</span>
// Initialize is a custom method to create the computed state.</span></span>
func</span> (</span>o </span>*</span>CommonOptions</span>)</span> Initialize</span>()</span> error</span> {</span> /* ... */</span> }</span></span></code></pre>
Bind the shared struct to the root command. Bind</code> registers it for auto-unmarshal: the bind pipeline populates it and calls Context()</code> to inject it before any PreRunE</code> or RunE</code> fires.</p>
structcli</span>.</span>Bind</span>(</span>rootC</span>,</span> commonOpts</span>)</span></span></code></pre>

Important:</strong> Bind</code> on root creates local</strong> flags on the root command. By default, Cobra rejects unknown flags before finding the subcommand, so app --loglevel info sub</code> would fail. Set rootC.TraverseChildren = true</code> so root parses its own flags first, then resolves the subcommand. Alternatively, bind the shared struct on each leaf command that needs the flags.</p>
</blockquote>
If you need to initialize computed state (like a logger) after unmarshal, use a PersistentPreRunE</code> hook: by the time it fires, commonOpts</code> is already populated:</p>
rootC</span>.</span>PersistentPreRunE</span> =</span> func</span>(</span>c</span> *</span>cobra</span>.</span>Command</span>,</span> args</span> []</span>string</span>)</span> error</span> {</span></span>
	// commonOpts is already populated by the bind pipeline.</span></span>
	return</span> commonOpts</span>.</span>Initialize</span>()</span></span>
}</span></span></code></pre>
Retrieve the state in subcommands. In your subcommand's RunE</code>, call .FromContext()</code> to retrieve the shared, initialized object.</p>
func</span>(</span>c </span>*</span>cobra</span>.</span>Command</span>,</span> args</span> []</span>string</span>)</span> error</span> {</span></span>
    config</span> := &</span>CommonOptions</span>{}</span></span>
    if</span> err</span> :=</span> config</span>.</span>FromContext</span>(</span>c</span>.</span>Context</span>());</span> err</span> !=</span> nil</span> {</span></span>
        return</span> err</span></span>
    }</span></span>
    config</span>.</span>Logger</span>.</span>Info</span>(</span>"Executing subcommand..."</span>)</span></span>
</span>
    return</span> nil</span></span>
},</span></span></code></pre>
This pattern ensures that subcommands remain decoupled while having access to a consistent, centrally-managed state.</p>

Note:</strong> The deprecated ContextOptions</code> interface (which embeds Options</code> and requires Attach</code>) still works for backward compatibility. New code should use ContextInjector</code> instead.</p>
</blockquote>
For a complete, runnable implementation of this pattern, see the loginsvc example located in the /examples/loginsvc</a> directory.</p>
🎯 Enum Registration§</a>
</h3>
Register string or integer enum types once in init()</code> and use them as plain struct fields. structcli handles flag creation, help text with allowed values, shell completion, validation, and config/env decoding automatically.</p>
String enums (RegisterEnum</code>)§</a>
</h4>
type</span> Environment string</span></span>
</span>
const</span> (</span></span>
	EnvDev</span>  Environment</span> =</span> "dev"</span></span>
	EnvProd</span> Environment</span> =</span> "prod"</span></span>
)</span></span>
</span>
func</span> init</span>() {</span></span>
	structcli</span>.</span>RegisterEnum</span>[</span>Environment</span>](</span>map</span>[</span>Environment</span>][]</span>string</span>{</span></span>
		EnvDev</span>:  {</span>"dev"</span>,</span> "development"</span>},</span>   // first string is canonical, rest are aliases</span></span>
		EnvProd</span>: {</span>"prod"</span>,</span> "production"</span>},</span></span>
	})</span></span>
}</span></span>
</span>
type</span> DeployOptions</span> struct</span> {</span></span>
	TargetEnv</span> Environment</span> `flag:"target-env" flagdescr:"Target environment" default:"dev" flagenv:"true"`</span></span>
}</span></span></code></pre>
This produces --target-env</code> with help text showing {dev,prod}</code>, shell completion for all values including aliases, and case-insensitive parsing that accepts both prod</code> and production</code>.</p>
Integer enums (RegisterIntEnum</code>)§</a>
</h4>
type</span> Priority int</span></span>
</span>
const</span> (</span></span>
	PriorityLow</span>    Priority</span> =</span> 0</span></span>
	PriorityMedium</span> Priority</span> =</span> 1</span></span>
	PriorityHigh</span>   Priority</span> =</span> 2</span></span>
)</span></span>
</span>
func</span> init</span>() {</span></span>
	structcli</span>.</span>RegisterIntEnum</span>[</span>Priority</span>](</span>map</span>[</span>Priority</span>][]</span>string</span>{</span></span>
		PriorityLow</span>:    {</span>"low"</span>},</span></span>
		PriorityMedium</span>: {</span>"medium"</span>,</span> "med"</span>},</span></span>
		PriorityHigh</span>:   {</span>"high"</span>,</span> "hi"</span>},</span></span>
	})</span></span>
}</span></span></code></pre>
Both functions panic on duplicate registration or empty values. Call them in init()</code> before any Define()</code> calls.</p>
See full example</a> for enum registration in a complete CLI.</p>
🪃 Custom Type Handlers§</a>
</h3>
For types that need custom parsing logic beyond what enum registration provides, structcli offers two mechanisms: per-type registration</strong> and per-field hooks</strong>.</p>
Per-type: RegisterType[T]</code>§</a>
</h4>
Register custom hooks for a type once in init()</code>. Every struct field of type T</code> uses them automatically: no special tags needed. RegisterType</code> panics on nil hooks or duplicate registration: call it in init()</code> before any Define</code>/Bind</code>.</p>
import</span> (</span></span>
    "github.com/leodido/structcli"</span></span>
    "github.com/leodido/structcli/values"</span></span>
)</span></span>
</span>
type</span> ListenAddress</span> struct</span> {</span></span>
    Host</span> string</span></span>
    Port</span> int</span></span>
    raw</span>  string</span></span>
}</span></span>
</span>
func</span> init</span>() {</span></span>
    structcli</span>.</span>RegisterType</span>[</span>ListenAddress</span>](</span>structcli</span>.</span>TypeHooks</span>[</span>ListenAddress</span>]{</span></span>
        Define</span>:</span> func</span>(</span>name</span>,</span> descr</span> string</span>,</span> sf</span> reflect</span>.</span>StructField</span>,</span> fv</span> reflect</span>.</span>Value</span>) (</span>pflag</span>.</span>Value</span>,</span> string</span>) {</span></span>
            ptr</span> :=</span> fv</span>.</span>Addr</span>().</span>Interface</span>().(*</span>ListenAddress</span>)</span></span>
            *</span>ptr</span> =</span> ListenAddress</span>{</span>Host</span>:</span> "localhost"</span>,</span> Port</span>:</span> 8080</span>,</span> raw</span>:</span> "localhost:8080"</span>}</span></span>
</span>
            return</span> values</span>.</span>NewString</span>(&</span>ptr</span>.</span>raw</span>),</span> descr</span> +</span> " (host:port)"</span></span>
        },</span></span>
        Decode</span>:</span> func</span>(</span>input</span> any</span>) (</span>any</span>,</span> error</span>) {</span></span>
            return</span> ParseListenAddress</span>(</span>input</span>.(</span>string</span>))</span></span>
        },</span></span>
    })</span></span>
}</span></span>
</span>
type</span> ServerOptions</span> struct</span> {</span></span>
    ListenAddr</span> ListenAddress</span> `flag:"listen" flagdescr:"Listen address"`</span></span>
}</span></span></code></pre>
Both Define</code> and Decode</code> are required. Panics on duplicate registration or nil hooks. Call in init()</code> before any Define</code>/Bind</code> calls.</p>
For enum types, prefer RegisterEnum</code>/RegisterIntEnum</code>: they wrap RegisterType</code> with less boilerplate.</p>
Per-field: FieldHookProvider</code> and FieldCompleter</code>§</a>
</h4>
When the same type needs different behavior in different fields, or when a standard type needs custom handling for a specific field, implement FieldHookProvider</code> on your options struct. Map keys are struct field names.</p>
type</span> ServerOptions</span> struct</span> {</span></span>
    ListenAddr</span> string</span> `flag:"listen" flagdescr:"Listen address"`</span></span>
    Mode</span>       string</span> `flag:"mode" flagdescr:"Server mode"`</span></span>
}</span></span>
</span>
func</span> (</span>o </span>*</span>ServerOptions</span>)</span> FieldHooks</span>()</span> map</span>[</span>string</span>]</span>structcli</span>.</span>FieldHook</span> {</span></span>
    return</span> map</span>[</span>string</span>]</span>structcli</span>.</span>FieldHook</span>{</span></span>
        "ListenAddr"</span>: {</span></span>
            Define</span>:</span> func</span>(</span>name</span>,</span> descr</span> string</span>,</span> sf</span> reflect</span>.</span>StructField</span>,</span> fv</span> reflect</span>.</span>Value</span>) (</span>pflag</span>.</span>Value</span>,</span> string</span>) {</span></span>
                ptr</span> :=</span> fv</span>.</span>Addr</span>().</span>Interface</span>().(*</span>string</span>)</span></span>
                *</span>ptr</span> =</span> "localhost:8080"</span></span>
</span>
                return</span> values</span>.</span>NewString</span>(</span>ptr</span>),</span> descr</span> +</span> " (host:port)"</span></span>
            },</span></span>
            Decode</span>:</span> func</span>(</span>input</span> any</span>) (</span>any</span>,</span> error</span>) {</span></span>
                return</span> input</span>,</span> nil</span></span>
            },</span></span>
        },</span></span>
    }</span></span>
}</span></span></code></pre>
For shell completion, implement FieldCompleter</code>:</p>
func</span> (</span>o </span>*</span>ServerOptions</span>)</span> CompletionHooks</span>()</span> map</span>[</span>string</span>]</span>structcli</span>.</span>CompleteHookFunc</span> {</span></span>
    return</span> map</span>[</span>string</span>]</span>structcli</span>.</span>CompleteHookFunc</span>{</span></span>
        "ListenAddr"</span>:</span> func</span>(</span>cmd</span> *</span>cobra</span>.</span>Command</span>,</span> args</span> []</span>string</span>,</span> toComplete</span> string</span>) ([]</span>string</span>,</span> cobra</span>.</span>ShellCompDirective</span>) {</span></span>
            return</span> []</span>string</span>{</span>"localhost:8080"</span>,</span> "0.0.0.0:8080"</span>,</span> "0.0.0.0:443"</span>},</span> cobra</span>.</span>ShellCompDirectiveNoFileComp</span></span>
        },</span></span>
    }</span></span>
}</span></span></code></pre>
FieldCompleter</code> works for any field that becomes a flag, not only fields with FieldHookProvider</code> hooks.</p>
Precedence§</a>
</h4>
Hook resolution follows this order (highest to lowest):</p>

FieldHookProvider</code></strong>: per-field hooks on the options struct</li>
RegisterType</code></strong> / RegisterEnum</code></strong>: per-type hooks in the global registry</li>
Built-in registry</strong>: time.Duration</code>, zapcore.Level</code>, slog.Level</code>, etc.</li>
</ol>
Completion precedence:</p>

If a completion function is already registered on a flag before Define</code>, structcli preserves it.</li>
If Define</code> auto-registers a FieldCompleter</code> hook, a later manual RegisterFlagCompletionFunc</code> on the same flag returns Cobra's already registered</code> error.</li>
</ul>
In values</a> we provide pflag.Value</code> implementations for standard types.</p>
See the custom types example</a> for a runnable demo of all three mechanisms, or the full example</a> for a complete CLI.</p>
🧱 Built-in Custom Types§</a>
</h3>
Type</th> Description</th> Example Values</th> Special Features</th></tr></thead>

zapcore.Level</code></td> Zap logging levels</td> debug</code>, info</code>, warn</code>, error</code>, dpanic</code>, panic</code>, fatal</code></td> Enum validation</td></tr>
slog.Level</code></td> Standard library logging levels</td> debug</code>, info</code>, warn</code>, error</code>, error+2</code>, ...</td> Level offsets: ERROR+2</code>, INFO-4</code></td></tr>
time.Duration</code></td> Time durations</td> 30s</code>, 5m</code>, 2h</code>, 1h30m</code></td> Go duration parsing</td></tr>
[]time.Duration</code></td> Duration slices</td> 30s,5m</code>, 1s,2m30s</code></td> Comma-separated / repeated flags</td></tr>
[]bool</code></td> Boolean slices</td> true,false,true</code></td> Comma-separated / repeated flags</td></tr>
[]uint</code></td> Unsigned integer slices</td> 1,2,3,42</code></td> Comma-separated / repeated flags</td></tr>
[]byte</code></td> Raw textual bytes</td> hello</code>, abc123</code></td> Raw textual input</td></tr>
structcli.Hex</code></td> Hex-decoded textual input</td> 68656c6c6f</code>, 48656c6c6f</code></td> Hex decoding</td></tr>
structcli.Base64</code></td> Base64-decoded textual input</td> aGVsbG8=</code>, YWJjMTIz</code></td> Base64 decoding</td></tr>
net.IP</code></td> IP address</td> 127.0.0.1</code>, 10.42.0.10</code>, 2001:db8::1</code></td> IP parsing</td></tr>
net.IPMask</code></td> IPv4 mask</td> 255.255.255.0</code>, ffffff00</code></td> Dotted or hex mask parsing</td></tr>
net.IPNet</code></td> CIDR subnet</td> 10.42.0.0/24</code>, 2001:db8::/64</code></td> CIDR parsing</td></tr>
[]net.IP</code></td> IP slices</td> 10.0.0.1,10.0.0.2</code></td> Comma-separated / repeated flags</td></tr>
[]string</code></td> String slices</td> item1,item2,item3</code></td> Comma-separated</td></tr>
[]int</code></td> Integer slices</td> 1,2,3,42</code></td> Comma-separated</td></tr>
map[string]string</code></td> String maps</td> env=prod,team=platform</code></td> key=value</code> pairs</td></tr>
map[string]int</code></td> Integer maps</td> cpu=2,memory=4</code></td> key=value</code> pairs with int parsing</td></tr>
map[string]int64</code></td> 64-bit integer maps</td> ok=1,fail=2</code></td> key=value</code> pairs with int64 parsing</td></tr>
</tbody></table>
Note on JSON output: net.IPMask</code> is a byte slice under the hood, so Go's encoding/json</code>
renders it as base64 (for example 255.255.255.0</code> appears as ////AA==</code>). This is expected.</p>
All built-in types support:</p>

Command-line flags with validation and help text</li>
Environment variables with automatic binding</li>
Configuration files (YAML, JSON, TOML)</li>
Type validation with helpful error messages</li>
</ul>
Slices and maps use the same contract across flags, env vars, and config.</p>
See examples/collections/main.go</a> for a runnable version of this example.</p>
type</span> AdvancedOptions</span> struct</span> {</span></span>
	Retries</span>   []</span>uint</span>          `flag:"retries" flagenv:"true"`</span></span>
	Backoffs</span>  []</span>time</span>.</span>Duration</span> `flag:"backoffs" flagenv:"true"`</span></span>
	FeatureOn</span> []</span>bool</span>          `flag:"feature-on" flagenv:"true"`</span></span>
	Labels</span>    map</span>[</span>string</span>]</span>string</span> `flag:"labels" flagenv:"true"`</span></span>
	Limits</span>    map</span>[</span>string</span>]</span>int</span>    `flag:"limits" flagenv:"true"`</span></span>
	Counts</span>    map</span>[</span>string</span>]</span>int64</span>  `flag:"counts" flagenv:"true"`</span></span>
}</span></span></code></pre>❯</span> myapp</span> --retries</span> 1,2,3</span> --backoffs</span> 1s,5s</span> --feature-on true</span>,</span>false --labels</span> env=prod,team=platform</span> --limits</span> cpu=8,memory=</span>16</span> --counts</span> ok=10,fail=</span>3</span></span>
❯</span> MYAPP_RETRIES=1,2,3 MYAPP_BACKOFFS=1s,5s MYAPP_FEATURE_ON=</span>true</span>,</span>false</span> MYAPP_LABELS=env=prod,team=platform MYAPP_LIMITS=cpu=8,memory=</span>16</span> MYAPP_COUNTS=ok=10,fail=</span>3</span> myapp</span></span>
❯</span> go run examples/collections/main.go</span> --config</span> examples/collections/config.yaml</span></span></code></pre>retries</span>:</span> "1,2,3"</span></span>
backoffs</span>:</span></span>
  -</span> 1s</span></span>
  -</span> 5s</span></span>
feature-on</span>:</span> "true,false"</span></span>
labels</span>:</span></span>
  env</span>:</span> prod</span></span>
  team</span>:</span> platform</span></span>
limits</span>:</span></span>
  cpu</span>:</span> 8</span></span>
  memory</span>:</span> 16</span></span>
counts</span>:</span> "ok=10,fail=3"</span></span></code></pre>🧰 Reusable Flag Kits§</a>
</h3>
The flagkit</code> package provides pre-built, embeddable flag structs that standardize common CLI flag declarations. Each type encapsulates one flag with an opinionated name, type, and default matching industry conventions. This gives AI agents and scripts a consistent vocabulary across CLIs built with structcli.</p>
import</span> "github.com/leodido/structcli/flagkit"</span></span>
</span>
type</span> LogsOptions</span> struct</span> {</span></span>
    flagkit</span>.</span>Follow</span>                                                    // --follow/-f (default: false)</span></span>
    Service</span> string</span> `flag:"service" flagshort:"s" flagdescr:"Service name" flagrequired:"true"`</span></span>
}</span></span>
</span>
func</span> (</span>o </span>*</span>LogsOptions</span>)</span> Attach</span>(</span>c</span> *</span>cobra</span>.</span>Command</span>)</span> error</span> {</span></span>
    if</span> err</span> :=</span> structcli</span>.</span>Define</span>(</span>c</span>,</span> o</span>);</span> err</span> !=</span> nil</span> {</span></span>
        return</span> err</span></span>
    }</span></span>
    flagkit</span>.</span>AnnotateCommand</span>(</span>c</span>)</span> // marks flagkit-owned flags for doc generation</span></span>
    return</span> nil</span></span>
}</span></span></code></pre>
Attach</code> is needed here because of the custom flagkit.AnnotateCommand</code> call. For structs without custom define-time logic, use structcli.Bind(cmd, opts)</code> instead: it handles both plain structs and Options</code> implementors.</p>
Available types:</p>
Type</th> Flag</th> Default</th> Description</th></tr></thead>

Follow</code></td> --follow</code> / -f</code></td> false</code></td> Opt-in streaming (agents won't hang)</td></tr>
LogLevel</code></td> --log-level</code></td> info</code></td> Log level via zapcore (alias for ZapLogLevel</code>)</td></tr>
ZapLogLevel</code></td> --log-level</code></td> info</code></td> Log level backed by zapcore.Level</code></td></tr>
SlogLogLevel</code></td> --log-level</code></td> info</code></td> Log level backed by slog.Level</code> (stdlib)</td></tr>
Output</code></td> --output</code> / -o</code></td> text</code></td> Output format (string enum, user-registered)</td></tr>
Verbose</code></td> --verbose</code> / -v</code></td> 0</code></td> Verbosity count (-v</code>, -vv</code>, -vvv</code>)</td></tr>
DryRun</code></td> --dry-run</code></td> false</code></td> Preview without making changes</td></tr>
Timeout</code></td> --timeout</code></td> 30s</code></td> Operation timeout (time.Duration</code>)</td></tr>
Quiet</code></td> --quiet</code> / -q</code></td> false</code></td> Suppress non-essential output</td></tr>
</tbody></table>
When the generate</code> package detects flagkit annotations, it emits a "Development Notes" section in AGENTS.md guiding AI coding agents to prefer flagkit types over ad-hoc flag declarations.</p>
See go doc github.com/leodido/structcli/flagkit</code> for the full taxonomy and composition examples.</p>
🎨 Beautiful, Organized Help Output§</a>
</h3>
Organize your --help</code> output into logical groups for better readability.</p>
❯</span> go run examples/full/main.go</span> --help</span></span>
# A demonstration of the structcli library with beautiful CLI features</span></span>
#</span></span>
# Usage:</span></span>
#   full [flags]</span></span>
#   full [command]</span></span>
#</span></span>
# Available Commands:</span></span>
#   completion  Generate the autocompletion script for the specified shell</span></span>
#   help        Help about any command</span></span>
#   logs        Show service logs</span></span>
#   preset      Demonstrate flag presets with validation and transformation</span></span>
#   srv         Start the server</span></span>
#   usr         User management</span></span>
#</span></span>
# Flags:</span></span>
#   -h, --help   help for full</span></span>
#</span></span>
# Utility Flags:</span></span>
#       --dry             </span></span>
#   -v, --verbose count</span></span>
#</span></span>
# Global Flags:</span></span>
#       --config string                   config file (fallbacks to: {/etc/full,{executable_dir}/.full,$HOME/.full,...}/config.{yaml,json,toml})</span></span>
#       --debug-options string[="text"]   debug output format (text, json)</span></span>
#       --jsonschema string[="true"]      output JSON Schema and exit (bare: this command, =tree: full subtree)</span></span>
#       --mcp                             serve MCP over stdio</span></span>
#</span></span>
# Reference:</span></span>
#   config-keys List all configuration file keys</span></span>
#   env-vars    List all environment variable bindings</span></span></code></pre>❯</span> go run examples/full/main.go srv</span> --help</span></span>
# Start the server with the specified configuration</span></span>
#</span></span>
# Usage:</span></span>
#   full srv [flags]</span></span>
#   full srv [command]</span></span>
#</span></span>
# Available Commands:</span></span>
#   version     Print version information</span></span>
#</span></span>
# Flags:</span></span>
#       --apikey string                  API authentication key</span></span>
#       --deep-setting string             (default "default-deep-setting")</span></span>
#       --deep.deeper.nodefault string</span></span>
#       --deeper-setting string           (default "default-deeper-setting")</span></span>
#   -h, --help                           help for srv</span></span>
#       --host string                    Server host (default "localhost")</span></span>
#   -p, --port int                       Server port</span></span>
#       --target-env string              Set the target environment {dev,prod,staging} (default "dev")</span></span>
#</span></span>
# Database Flags:</span></span>
#       --database.maxconns int   Max database connections (default 10)</span></span>
#       --db-url string           Database connection URL</span></span>
#</span></span>
# Logging Flags:</span></span>
#       --log-file string           Log file path</span></span>
#       --log-level zapcore.Level   Set log level {debug,info,warn,error,dpanic,panic,fatal} (default info)</span></span>
#</span></span>
# Network Flags:</span></span>
#       --advertise-cidr ipNet    Advertised service subnet (CIDR) (default 127.0.0.0/24)</span></span>
#       --bind-ip ip              Bind interface IP (default 127.0.0.1)</span></span>
#       --bind-mask ipMask        Bind interface mask (default ffffff00)</span></span>
#       --trusted-peers ipSlice   Trusted peer IPs (comma separated) (default 127.0.0.2,127.0.0.3)</span></span>
#</span></span>
# Security Flags:</span></span>
#       --token-base64 bytesBase64   Token bytes encoded as base64 (default aGVsbG8=)</span></span>
#       --token-hex bytesHex         Token bytes encoded as hex (default 68656c6c6f)</span></span>
#</span></span>
# Global Flags:</span></span>
#       --config string                   config file (fallbacks to: {/etc/full,{executable_dir}/.full,$HOME/.full,...}/config.{yaml,json,toml})</span></span>
#       --debug-options string[="text"]   debug output format (text, json)</span></span>
#       --jsonschema string[="true"]      output JSON Schema and exit (bare: this command, =tree: full subtree)</span></span>
#       --mcp                             serve MCP over stdio</span></span>
#</span></span>
# Use "full srv [command] --help" for more information about a command.</span></span></code></pre>🌐 WebAssembly (WASM)§</a>
</h3>
structcli avoids reflect.Value.MethodByName</code> and reflect.Value.Call</code>, so the Go compiler's dead-code elimination (DCE) works correctly and WASM binaries stay lean. All features work under GOOS=wasip1 GOARCH=wasm</code> with the standard Go compiler, including custom type hooks (RegisterType[T]</code>, FieldHookProvider</code>), JSON Schema generation, structured errors, and debug output.</p>
Build and run any structcli program as WASM:</p>
GOOS</span>=</span>wasip1</span> GOARCH</span>=</span>wasm</span> go</span> build</span> -o</span> myapp.wasm .</span></span>
wasmtime</span> run</span> --dir=/</span> myapp.wasm serve</span> --port</span> 8080</span></span></code></pre>
This means structcli CLIs can run in sandboxed WASM runtimes, edge functions, and browser-based environments. Combined with --jsonschema</code> and --mcp</code>, an agent can discover the CLI contract, call it in a sandboxed WASM runtime, and handle structured failures without ever touching the host OS.</p>
🏷️ Available Struct Tags§</a>
</h2>
Use these tags in your struct fields to control the behavior:</p>
Tag</th> Description</th> Example</th></tr></thead>

flag</code></td> Sets a custom name for the flag (otherwise, generated from the field name)</td> flag:"log-level"</code></td></tr>
flagpreset</code></td> Defines CLI-only preset aliases for this field's flag. Each preset is <alias-flag-name>=<value-for-this-field-flag></code>. No env/config keys are created.</td> flagpreset:"logeverything=5;logquiet=0"</code></td></tr>
flagshort</code></td> Sets a single-character shorthand for the flag</td> flagshort:"l"</code></td></tr>
flagdescr</code></td> Provides the help text for the flag</td> flagdescr:"Logging level"</code></td></tr>
default</code></td> Sets the default value for the flag</td> default:"info"</code></td></tr>
flagenv</code></td> Enables binding to an environment variable ("true"</code>, "false"</code>, or "only"</code>)</td> flagenv:"true"</code></td></tr>
flagrequired</code></td> Marks the flag as required ("true"</code>/"false"</code>)</td> flagrequired:"true"</code></td></tr>
flaghidden</code></td> Hides the flag from help/usage output and machine-readable schemas while keeping it fully functional ("true"</code>/"false"</code>)</td> flaghidden:"true"</code></td></tr>
flaggroup</code></td> Assigns the flag to a group in the help message</td> flaggroup:"Database"</code></td></tr>
flagignore</code></td> Skips creating a flag for this field ("true"</code>/"false"</code>)</td> flagignore:"true"</code></td></tr>
flagtype</code></td> Specifies a special flag type. Currently supports count</code></td> flagtype:"count"</code></td></tr>
</tbody></table>
flagpreset</code> is syntactic sugar: it creates alias flags that set the canonical flag value.
Format: <alias>=<value></code>; multiple entries can be separated by ;</code> or ,</code>.
Example: flagpreset:"logeverything=5;logquiet=0"</code> makes --logeverything</code> behave like --loglevel=5</code>.
If both alias and canonical flags are passed, the last assignment in argv wins.
It does not bypass transform/validate flow.</p>
flaghidden:"true" + flagenv:"true"</code> vs flagenv:"only"</code>:</strong></p>

flaghidden:"true" + flagenv:"true"</code>: hidden from help, but accepts CLI input</strong> via --flag=value</code>. Use for flags that should be discoverable only by advanced users or scripts.</li>
flagenv:"only"</code>: hidden from help, rejects CLI input</strong> at runtime. The field is settable only via environment variable or config file. Use for secrets and deployment-time configuration that should never appear on a command line.</li>
</ul>
flagenv:"only"</code> is incompatible with flagshort</code>, flagpreset</code>, and flagtype</code> (these are CLI-only concepts). It supports flagdescr</code>, flaggroup</code>, flagrequired</code>, and default</code>. FieldHookProvider</code> Define/Decode hooks work normally on flagenv:"only"</code> fields (the flag is created then hidden). FieldCompleter</code> hooks are skipped since hidden flags have no CLI completion.</p>
📖 Documentation§</a>
</h2>
For comprehensive documentation and advanced usage patterns, visit the documentation</a>.</p>
Start here for repo-local guides:</p>

AI-Native CLIs guide</a></li>
Structured error example walkthrough</a></li>
Examples directory</a></li>
</ul>
🤝 Contributing§</a>
</h2>
Contributions are welcome!</p>
Please feel free to submit a Pull Request.</p>
🤝 Contributing §</a> </h2>
Contributions are welcome!</p>
Please feel free to submit a Pull Request.</p>

leodido.dev - Viper

structcli
