Conventions that have worked well for go-based CLIs

[rianjs]

CLI Development Conventions

Breadcrumbs for Claude (and humans) to follow when working on this codebase.

Design Principles

Composability & Orthogonality

Commands should be independent, single-purpose units that don't overlap:

• gro mail search / gro mail read / gro mail thread - each does one thing
• jtk issue list / jtk issue get / jtk issue create - CRUD as separate commands
• cfl page view vs cfl page edit - reading vs writing are distinct
• sfdc bulk import / sfdc bulk export - large data ops separate from CRUD
• Each command does one thing well

Patterns Before API Surface

Establish infrastructure before writing feature commands:

1. Project structure, CI/CD, distribution
2. Authentication and secure storage
3. Configuration management
4. Output formatting (table/JSON/plain)
5. THEN add API commands

Standard Command Conventions

Setup & Config Pattern:

gro init               # Interactive OAuth setup wizard
gro config show        # Display current configuration
gro config test        # Verify credentials work
gro config clear       # Remove stored credentials

jtk init               # Same pattern for Jira
cfl init               # Same pattern for Confluence
sfdc init              # Same pattern for Salesforce

Resource Commands Pattern:

cfl page list                  # List resources
cfl page view <id>             # Get single resource (read-only alias)
cfl page create                # Create resource
cfl page edit <id>             # Update resource
cfl page delete <id>           # Delete resource

jtk issue list
jtk issue get <id>
jtk issue create
jtk issue update <id>

gro mail search <query>        # Read-only CLI, no create/update/delete
gro mail read <id>
gro calendar events

Workflow

Issue → PR → Close → Next

Atomic units of work:

1. Create GitHub issue describing the work
2. Create feature branch
3. Implement with tests
4. Open PR that references "Closes #N"
5. CI passes, merge via squash
6. Move to next issue

TDD Assessment Gate

Before merging significant features:

1. Implementation complete
2. Spawn TDD assessment agent to review coverage
3. Address gaps identified
4. Then merge

Commit Message Conventions

feat(scope): add new feature      # Triggers release
fix(scope): fix a bug             # Triggers release
refactor(scope): restructure      # No release
test(scope): add tests            # No release
docs(scope): documentation        # No release
ci(scope): CI/CD changes          # No release
chore(scope): maintenance         # No release

Commits should never include any mention of Claude, Anthropic, or any other AI tool. Consider creating a precommit hook like this:

# commit-msg hook: Disallow AI tool mentions in commit messages

COMMIT_MSG_FILE="$1"
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

# Case-insensitive patterns to block
BLOCKED_PATTERNS=(
    "claude"
    "anthropic"
    "chatgpt"
    "openai"
    "copilot"
    "gemini"
    "bard"
    "gpt-[0-9]"
    "gpt [0-9]"
    "ai-generated"
    "ai generated"
    "ai-assisted"
    "ai assisted"
)

for pattern in "${BLOCKED_PATTERNS[@]}"; do
    if echo "$COMMIT_MSG" | grep -iqE "$pattern"; then
        echo "ERROR: Commit message contains blocked term matching '$pattern'"
        echo "AI tool mentions are not allowed in commit messages."
        exit 1
    fi
done

exit 0

Testing Patterns

Table-Driven Tests

tests := []struct {
    name    string
    input   string
    want    string
    wantErr bool
}{
    {"valid input", "foo", "bar", false},
    {"empty input", "", "", true},
}
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        // test logic
    })
}

HTTP Mocking with httptest

server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    assert.Equal(t, "/rest/api/3/issue/TEST-1", r.URL.Path)
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(expectedResponse)
}))
defer server.Close()

client := api.NewClient(server.URL, "email", "token")

Injectable Dependencies for Testability

// Use Options struct pattern
opts := &root.Options{
    Stdout: &bytes.Buffer{},
    Stdin:  strings.NewReader("yes\n"),  // For confirmation prompts
}
opts.SetAPIClient(mockClient)

cmd := deleteCmd.NewCommand(opts)
cmd.SetArgs([]string{"TEST-123", "--confirm"})
err := cmd.Execute()

What NOT To Do

• No giant interface packages
• No DI frameworks (wire, dig)
• No reflection-based mocking
• Don't mock what you can test with httptest

Architecture

Directory Structure

cmd/<binary>/main.go       # Entry point (e.g., cmd/gro/, cmd/jtk/, cmd/cfl/)
api/                       # Public API client library
internal/cmd/              # Cobra commands
  root/                    # Root command, Options struct
  initcmd/                 # <tool> init
  configcmd/               # <tool> config {show,test,clear}
  <feature>cmd/            # Feature-specific commands
internal/auth/             # OAuth/auth implementation
internal/config/           # Configuration file management
internal/keychain/         # Secure token storage (gro, sfdc)
internal/view/             # Output formatting (table/JSON/plain)

Register Pattern

Each command package exports a Register function:

func Register(parent *cobra.Command, opts *root.Options) {
    parent.AddCommand(NewCommand(opts))
}

CI/CD & Repository Settings

Branch Protection (main)

• Require PRs with 1 approval
• Required status checks: build, test, lint
• Require signed commits
• Require linear history
• No force pushes

Merge Settings

• Squash merge only
• Delete branch on merge
• No merge commits, no rebase merge

Cross-Platform Support

• Windows, Linux, macOS
• amd64 and arm64 architectures
• GoReleaser for builds
• Homebrew, Chocolatey, Winget, Snap for distribution