Go Subcommand

CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

CLI Reference#

The gosubc tool has the following commands:

`generate`#

Generates the Go code for your CLI.

gosubc generate [flags]

Flags:

--dir <path>: The project root directory containing go.mod. Defaults to ..
--man-dir <path>: Directory to generate Unix man pages in. If omitted, no man pages are generated.

`list`#

Lists all identified subcommands in the project. Useful for debugging parsing.

gosubc list [flags]

Flags:

--dir <path>: The project root directory.

`validate`#

Validates subcommand definitions for conflicts or errors.

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started#

Let’s build a simple CLI application named greet.

1. Create a Go Module#

mkdir greet
cd greet
go mod init example.com/greet

2. Define a Command#

Create main.go and define your command function.

package main

import "fmt"

// Hello is a subcommand `greet hello`
// Prints a greeting.
func Hello(name string) {
 fmt.Printf("Hello, %s!\n", name)
}

func main() {
 // This will be replaced by the generated code usage,
 // but for now you can leave it empty or use it to run the generated cmd.
}

3. Configure Generation#

Create a generate.go file to instruct go generate.

Defining Commands

Mon, 01 Jan 0001 00:00:00 +0000

Defining Commands#

Commands are defined by adding specific comments to your Go functions.

Syntax#

// FunctionName is a subcommand `root-cmd sub-cmd...`
// Description text...

FunctionName: The name of the Go function to execute.
root-cmd: The name of your root application (e.g., git, kubectl).
sub-cmd…: A space-separated list of subcommands (e.g., remote add).

Description#

The text following the command definition or on subsequent lines is used as the command description in usage text.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

To use Go Subcommand, you need to install the gosubc CLI tool.

Prerequisites#

Go: Version 1.18 or later.

Installing `gosubc`#

Run the following command to install the latest version:

go install github.com/arran4/go-subcommand/cmd/gosubc@latest

Verify the installation:

gosubc --help

Adding to Your Project#

You don’t need to import go-subcommand in your application logic files unless you are using specific helper types. The generated code will reside in a separate package (usually cmd/appname).

Flags & Parameters

Mon, 01 Jan 0001 00:00:00 +0000

Flags & Parameters#

go-subcommand automatically maps your function parameters to command-line flags and arguments.

Automatic Mapping#

Function parameters are converted to flags by default.

func Server(port int, verbose bool)

Generates flags:

--port <int>
--verbose (boolean flag)

Flag names are automatically converted to kebab-case (e.g., maxRetries -> --max-retries).

Customizing Flags#

You can customize flags using comments. There are three ways to define them, in order of priority:

Flags Block: A Flags: block in the function documentation.
Inline Comment: Comment on the same line as the parameter.
Preceding Comment: Comment on the line before the parameter.

1. Flags Block (Highest Priority)#

// MyCmd is a subcommand `app cmd`
// Flags:
// port: default: 8080 description: Port to listen on
func MyCmd(port int) {}

2. Inline Comment#

func MyCmd(
 port int, // default: 8080 description: Port to listen on
) {}

3. Preceding Comment#

// default: 8080 description: Port to listen on
port int

Syntax Reference#

The parameter definition syntax supports several attributes:

Agent Skills

Mon, 01 Jan 0001 00:00:00 +0000

Agent Skills#

gosubc supports installing and managing AI Agent Skills. Skills are Markdown files (SKILL.md) and supporting files that teach AI coding assistants (like Cursor, Copilot, or generic agents) how to use your CLI properly.

Managing Skills#

gosubc includes a built-in skill command group to manage these agent instructions.

Installing a Skill#

You can install a skill from a local directory or a remote git repository.

# Install a local skill
gosubc skill install ./my-local-skill

# Install a skill from a GitHub repository (e.g., github.com/owner/repo)
gosubc skill install owner/repo

Scopes: By default, skills are installed to the user scope (e.g., ~/.agents/skills/). You can install a skill for a specific project by using --scope project, which places it in .agents/skills/ in your current working directory.

Generator design principles

Mon, 01 Jan 0001 00:00:00 +0000

Generator design principles#

go-subcommand owns command execution and process policy. User functions supply actions, initialization and dependencies. Templates remain an optional escape hatch.

The preferred workflow is deliberately small: write a Go function, document it with a Go comment, generate, and run. A user should not need to understand the generated entry point, implement dispatch, manually register callbacks, or customize templates to get a usable CLI.

For example, the ordinary current workflow begins with:

Project generation configuration

Mon, 01 Jan 0001 00:00:00 +0000

gosubc generate --config gosubc.mdc reads optional generator settings. Both .mdc and .mdconf are supported candidates; neither filename is required. Generated applications do not read this file or depend on go-subcommand at runtime.

format-version: 1
cli-parser: gnu
recursive: true
emit-go-generate: false
paths:
- commands

Explicit flags override file values, including --recursive=false and --prov-version=. File settings override built-in defaults. Settings belong at the top, without a # Configuration heading. Generator settings are dir, man-dir, parser-name, cli-parser, paths, recursive, force, clean, replace-templates, project-provenance (alias project), timestamp, emit-go-generate, prov-version, prov-commit, and prov-date. Keys ignore case, hyphens and underscores. version is an alias for format-version, and one version declaration is required.

Functionless command metadata

Mon, 01 Jan 0001 00:00:00 +0000

Use a package or standalone comment to describe a root or child without registering an executable action:

// App is a command `app` -- Manage jobs.
// More application help.
package commands

// Generate is a subcommand `app generate` -- Generate jobs.
func Generate() { fmt.Println("generate") }

app prints described help on stderr and exits 0. app generate prints generate on stdout. app unknown returns an unknown-command error and status 1. app help, app usage, app --help, recursive help and version keep normal dispatch behaviour and do not acquire business providers.

Generated errors and process boundary

Mon, 01 Jan 0001 00:00:00 +0000

Generated cmd packages expose ErrUsage and *UsageError. These are generated application types; applications do not import go-subcommand at runtime.

var usage *cmd.UsageError
if errors.Is(err, cmd.ErrUsage) && errors.As(err, &usage) {
 fmt.Printf("%s: kind=%s flag=%s\n", usage.CommandPath, usage.Kind, usage.Flag)
}

The stable kinds are UsageUnknownCommand, UsageUnknownFlag, UsageMissingFlagValue, UsageInvalidValue, UsageInvalidArguments, and UsageMissingRequiredFlag. The error holds a canonical command path, a flag name without leading dashes where applicable, an optional underlying cause, and a presentation message. Classification never depends on matching that message. Causes remain available through errors.Is and errors.As. Application-provided usage errors and explicit exit errors retain their wrappers when returned from dispatch.

No-command policy

Mon, 01 Jan 0001 00:00:00 +0000

Use functionless root metadata to require a selected command:

// App is a command `app` -- Run jobs.
// No command: error
package commands

// Run is a subcommand `app run` -- Run a job.
func Run() { fmt.Println("run") }

Or place the same directive in native configuration:

format-version: 1
# Commands
```command: app
Description: Run jobs.
No command: error
```

Invocation	stdout	stderr	Status
`app`	empty	`Error: no command provided`	1
`app --`	empty	`Error: no command provided`	1
`app run`	`run`	empty	0
`app help`, `app usage`, `app --help`	empty	normal help	0
`app version`	normal version	empty	0
`app missing`	empty	usage and unknown-command error	1
`app -- run`	empty	usage and unknown-command error	1

The directive is an execution policy, independent of executable routing. When omitted, bare invocation preserves existing help and status 0. Only error is accepted. Empty/unknown values, duplicate declarations and policies on children are generation errors with source filename and line diagnostics. A real root action or any default route, including a help route or a child marked default, conflicts with the policy. Put it in root metadata rather than an action comment.

Go Subcommand

CLI Reference

CLI Reference#

generate#

list#

validate#

Getting Started

Getting Started#

1. Create a Go Module#

2. Define a Command#

3. Configure Generation#

Defining Commands

Defining Commands#

Syntax#

Description#

Installation

Installation#

Prerequisites#

Installing gosubc#

Adding to Your Project#

Flags & Parameters

Flags & Parameters#

Automatic Mapping#

Customizing Flags#

1. Flags Block (Highest Priority)#

2. Inline Comment#

3. Preceding Comment#

Syntax Reference#

Agent Skills

Agent Skills#

Managing Skills#

Installing a Skill#

Generator design principles

Generator design principles#

Project generation configuration

Functionless command metadata

Generated errors and process boundary

No-command policy

`generate`#

`list`#

`validate`#

Installing `gosubc`#