Usage on Go Subcommand

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.

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.