# What Files Are Typically Found in the cmd Directory of a Go Project?

> Discover files within a Go project's cmd directory. Learn how each sub-directory, including main.go, creates unique binaries, config, and tests for your Go applications.

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

---

**The `cmd` directory in a Go project like `gastownhall/gastown` contains executable entry points, where each sub-directory houses a [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) file that compiles into a separate binary, along with supporting configuration files and `*_test.go` test files.**

The `gastownhall/gastown` repository follows standard Go project layout conventions by organizing its command-line tools within the `cmd` directory. This structure keeps binary entry points isolated from library code, enabling developers to build multiple distinct executables from a single codebase.

## The Standard cmd Directory Structure

In Go projects, the `cmd` folder serves as the conventional location for **entry-point binaries**. Each immediate sub-directory represents a distinct executable application that can be built independently.

### Entry Point Binaries

Every sub-directory under `cmd` typically contains a [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) file that defines the entry point for that specific tool. This pattern allows a single repository to produce multiple standalone programs while maintaining clear separation of concerns.

### The Main CLI (cmd/gt)

The `cmd/gt/` directory contains the primary Gastown command-line client. The file [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go) serves as the entry point for the `gt` CLI, initializing the application and wiring up all sub-commands imported from `internal/cmd`.

### Supporting Tools (cmd/gt-proxy-server and cmd/gt-proxy-client)

The repository includes additional utility binaries following the same pattern:

- **`cmd/gt-proxy-server/`** – Contains [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) and [`config.go`](https://github.com/gastownhall/gastown/blob/main/config.go) (along with [`config_test.go`](https://github.com/gastownhall/gastown/blob/main/config_test.go)), implementing a tiny HTTP proxy server used by the CLI to communicate with background services.
- **`cmd/gt-proxy-client/`** – Houses a minimal [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) that implements a lightweight client forwarding requests to the proxy server.

## Sub-Command Organization

While the `cmd` directory contains the binary entry points, the actual command implementations for the main `gt` CLI reside in `internal/cmd/`. This separation allows the main binary to import and expose multiple sub-commands:

- **[`internal/cmd/wl.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl.go)** – Implements the `wl` (work-list) sub-command.
- **[`internal/cmd/tap.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/tap.go)** – Handles the `tap` (polecat interaction) sub-command.
- **[`internal/cmd/sling.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/sling.go)** – Contains core logic for the `sling` deployment orchestration command.
- **[`internal/cmd/status.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/status.go)** – Provides the `status` command to inspect system state.

Each sub-command file includes corresponding test files such as [`internal/cmd/wl_test.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/wl_test.go), demonstrating the standard Go pattern of keeping tests alongside source code.

## File Types and Naming Conventions

The `cmd` directory and its sub-directories contain strictly **Go source files**:

- **`.go` files** – Implementation source code (e.g., [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go), [`config.go`](https://github.com/gastownhall/gastown/blob/main/config.go)).
- **`*_test.go` files** – Unit tests accompanying the source files.

No other languages or resource files appear in these directories. According to the `gastownhall/gastown` source code, any non-code assets (templates, static files) are kept elsewhere in the repository, such as under `assets/` or `internal/`.

## Building and Testing Executables

### Building the Main CLI

To compile the primary Gastown binary from the `cmd/gt` package:

```bash

# Build the primary binary from the cmd/gt package

go build -o bin/gt ./cmd/gt

# Run it

./bin/gt --help

```

### Adding a New Sub-Command

Create a new file in `internal/cmd/` to extend the CLI:

```go
// internal/cmd/hello.go
package cmd

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

func init() {
    RootCmd.AddCommand(helloCmd)
}

var helloCmd = &cobra.Command{
    Use:   "hello",
    Short: "Print a friendly greeting",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Hello, Gastown!")
    },
}

```

Then rebuild to include the new command:

```bash

# Re-build the CLI to include the new command

go build -o bin/gt ./cmd/gt
./bin/gt hello

# → Hello, Gastown!

```

### Running Tests

Execute tests for specific sub-commands:

```bash

# Execute tests only for the `wl` (worklist) command

go test ./internal/cmd -run TestWl

```

## Summary

- The `cmd` directory contains **entry-point binaries**, with each sub-directory compiling into a separate executable.
- [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go) serves as the primary CLI entry point for `gastownhall/gastown`.
- Supporting tools like [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go) and [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go) follow the same pattern with additional configuration files.
- Sub-command implementations reside in `internal/cmd/` (e.g., [`wl.go`](https://github.com/gastownhall/gastown/blob/main/wl.go), [`tap.go`](https://github.com/gastownhall/gastown/blob/main/tap.go), [`sling.go`](https://github.com/gastownhall/gastown/blob/main/sling.go), [`status.go`](https://github.com/gastownhall/gastown/blob/main/status.go)) alongside their `*_test.go` files.
- Only Go source files (`.go`) and test files (`*_test.go`) appear in these directories; no other languages or assets are stored here.

## Frequently Asked Questions

### What is the difference between the cmd and internal/cmd directories?

The `cmd` directory contains executable entry points with [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) files that compile into standalone binaries. The `internal/cmd` directory (as seen in `gastownhall/gastown`) contains the actual implementation logic for sub-commands like `wl`, `tap`, and `sling`, which are imported and wired up by the main `gt` binary in `cmd/gt`.

### Can I put non-Go files in the cmd directory?

No. According to the `gastownhall/gastown` source code, the `cmd` directory contains only **regular Go source files** (`.go`) and **Go test files** (`*_test.go`). Non-code assets such as templates or static files are kept elsewhere in the repository, typically under `assets/` or other dedicated directories.

### How do I build a specific binary from the cmd directory?

Run `go build` targeting the specific sub-directory. For example, to build the proxy server: `go build -o bin/gt-proxy-server ./cmd/gt-proxy-server`. This produces a standalone binary representing that specific tool or service.

### Why does each sub-directory in cmd need its own main.go?

Each sub-directory in `cmd` represents a distinct executable application. The [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) file provides the entry point for that specific binary. This structure allows a single repository to produce multiple separate tools (like `gt`, `gt-proxy-server`, and `gt-proxy-client`) while maintaining clear separation of concerns.