# How Commands Are Organized in the gastownhall/gastown cmd Directory

> Discover how gastownhall/gastown cmd commands are organized using Cobra. Learn about root commands and modular sub-command registration via Go init() functions.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: internals
- Published: 2026-07-07

---

**The gastown CLI organizes commands into seven logical groups using the Cobra framework, with the root command defined in [`internal/cmd/root.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/root.go) and sub-commands auto-registered via Go's `init()` functions in modular files.**

The gastownhall/gastown project structures its command-line interface using a clean, modular approach that leverages the Cobra library. All CLI logic resides in the `internal/cmd/` directory, where each functional area is encapsulated in its own source file and assigned to one of seven semantic groups. This architecture ensures that the `gt` binary presents a logically organized help interface while maintaining extensible, maintainable code.

## Root Command and Group Architecture

The entry point for all CLI operations is [`internal/cmd/root.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/root.go), which instantiates a `rootCmd` named `gt`. This file defines seven logical group constants that control the order and categorization of commands in the help output.

The groups are declared between lines 33 and 55 in [`root.go`](https://github.com/gastownhall/gastown/blob/main/root.go) and attached to the root command via `rootCmd.AddGroup()`. Each sub-command then sets its `GroupID` field to associate itself with one of these categories.

### The Seven Command Groups

The [`root.go`](https://github.com/gastownhall/gastown/blob/main/root.go) file organizes commands into the following semantic categories:

- **GroupWork** – **Work Management:** Commands that schedule, execute, or query work (e.g., `gt wl`, `gt up`, `gt start`).
- **GroupAgents** – **Agent Management:** Commands for starting, listing, or interacting with AI agents (e.g., `gt role`, `gt polecat`).
- **GroupComm** – **Communication:** Commands for inter-agent messaging (`gt nudge`, `gt mail`).
- **GroupServices** – **Services:** Long-running background services (`gt refinery`, `gt reaper`).
- **GroupWorkspace** – **Workspace:** Commands that manipulate the Gas Town workspace (`gt init`, `gt rig`).
- **GroupConfig** – **Configuration:** Settings-related commands (`gt config`, `gt plugin`).
- **GroupDiag** – **Diagnostics:** Debugging and inspection commands (`gt version`, `gt doctor`).

When users run `gt --help`, Cobra renders commands under these group headings, making it easy to discover related functionality.

## Command Registration Pattern

Each file in `internal/cmd/` follows a consistent pattern to wire commands into the hierarchy:

1. Define a package-level `cobra.Command` variable (typically named `<name>Cmd`).
2. Set the `GroupID` field to one of the constants exported from [`root.go`](https://github.com/gastownhall/gastown/blob/main/root.go).
3. Configure flags in an `init()` function.
4. Register the command using `rootCmd.AddCommand()` or attach it to a parent command.

Because Go automatically executes `init()` functions when the package loads, simply importing the `cmd` package in [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) registers all commands without manual bookkeeping.

```go
// Example from internal/cmd/wl.go
var wlCmd = &cobra.Command{
    Use:     "wl",
    GroupID: GroupWork,               // ← belongs to the “Work Management” group
    Short:   "Wasteland federation commands",
    RunE:    requireSubcommand,
}

func init() {
    rootCmd.AddCommand(wlCmd)    // ← registers with the root
}

```

Sub-commands follow the same pattern, attaching to their parent via `parentCmd.AddCommand()`. For example, in [`wl.go`](https://github.com/gastownhall/gastown/blob/main/wl.go), the `wl join` sub-command is wired in the same `init()` block:

```go
func init() {
    wlJoinCmd.Flags().StringVar(&wlJoinHandle, "handle", "", "Rig handle for registration")
    wlCmd.AddCommand(wlJoinCmd)  // ← sub-command attached to wl
    rootCmd.AddCommand(wlCmd)    // ← wl attached to the root
}

```

## File Organization and Key Source Files

The `internal/cmd/` directory uses a flat structure where each functional domain owns its file. This separation of concerns allows developers to locate logic quickly and prevents merge conflicts in monolithic files.

- **[`internal/cmd/root.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/root.go)** – Defines the root command, group constants, and global flags.
- **[`internal/cmd/wl.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl.go)** – Implements the `gt wl` command and its sub-commands (e.g., `join`).
- **[`internal/cmd/sling.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/sling.go)** – Handles work-dispatch commands (`gt sling`).
- **[`internal/cmd/rig.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/rig.go)** – Workspace-related commands (`gt rig`).
- **[`internal/cmd/role.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/role.go)** – Agent-management commands (`gt role`).
- **[`internal/cmd/mail.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/mail.go)** – Communication commands (`gt mail`).
- **[`internal/cmd/version.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/version.go)** – Diagnostic command showing the tool version.
- **[`internal/cmd/upgrade.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/upgrade.go)** – Maintenance commands for migrations.

The entry point in [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) simply imports the `cmd` package and calls `rootCmd.Execute()`, relying on the automatic registration via `init()` functions:

```go
// main.go
func main() {
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

```

## Practical Example: Adding a New Command

To extend the CLI, create a new file in `internal/cmd/` following the established pattern. Here is a complete example that adds a `gt greet` command under the **Diagnostics** group:

```go
// internal/cmd/greet.go
package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var greetCmd = &cobra.Command{
    Use:     "greet <name>",
    GroupID: GroupDiag,               // puts it under Diagnostics
    Short:   "Print a friendly greeting",
    Args:    cobra.ExactArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        fmt.Printf("Hello, %s! 👋\n", args[0])
        return nil
    },
}

func init() {
    rootCmd.AddCommand(greetCmd) // registers with the root
}

```

After rebuilding, `gt --help` displays `greet` under the **Diagnostics** section, and `gt greet Alice` executes the command.

## Summary

- The root command in [`internal/cmd/root.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/root.go) defines seven logical groups (`GroupWork`, `GroupAgents`, etc.) that organize the help output.
- Each command file uses Go's `init()` function to auto-register itself with `rootCmd.AddCommand()`, eliminating manual wiring.
- The `GroupID` field assigns commands to semantic categories, ensuring consistent CLI documentation.
- The modular file structure allows adding new commands by creating a single file without modifying core logic.

## Frequently Asked Questions

### What CLI framework does gastown use?

The gastown project uses the **Cobra** framework for Go. Cobra provides the command structure, flag parsing, and help generation used throughout the `internal/cmd/` directory.

### How do I add a new command to the gastown CLI?

Create a new file in `internal/cmd/`, define a `cobra.Command` variable, set the appropriate `GroupID` from [`root.go`](https://github.com/gastownhall/gastown/blob/main/root.go), and call `rootCmd.AddCommand()` inside an `init()` function. The command automatically appears in the help output under its designated group.

### Why are commands organized into groups?

The group constants (`GroupWork`, `GroupAgents`, etc.) control the visual organization of `gt --help`. This taxonomy keeps related commands together, making the interface discoverable for users and maintainable for developers who know exactly which file contains which feature.

### Where is the entry point for the gastown CLI?

The entry point is the `main()` function in the repository root (typically [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) or [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)). This function imports the `internal/cmd` package and calls `rootCmd.Execute()`, which triggers Cobra's command routing and invokes the appropriate `RunE` function.