# Output Format of the Commands in the gastownhall/gastown cmd Directory

> Understand the output format of gastownhall gastown commands. Learn how plain-text and internal JSON formats are used for efficient command-line interaction and data exchange.

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

---

**The command-line tools in the `gastownhall/gastown` repository primarily produce human-readable plain-text output, except for the `gt-proxy-client` which uses an internal JSON wire format to communicate with the proxy server while still presenting plain-text to the end user.**

The `gastownhall/gastown` repository contains the Gas Town CLI toolchain, a collection of utilities for managing agents and development workflows. Understanding the output format of these commands is essential for scripting and integration work. According to the source code, the binaries in the `cmd` directory follow a consistent pattern: they emit human-readable text to STDOUT and STDERR, with one architectural exception involving the proxy client's internal communication protocol.

## Overview of the cmd Binaries

Three main binaries reside in the `cmd` directory, each with distinct output characteristics:

- **`gt`** ([`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)): The primary CLI for workspace management and agent operations
- **`gt-proxy-server`** ([`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)): An mTLS HTTP proxy daemon that forwards calls from containers to the host
- **`gt-proxy-client`** ([`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go)): A thin wrapper installed inside containers to forward commands to the proxy server

While the first two emit structured logs and human-readable text directly, the third uses JSON for internal communication but ultimately presents plain-text output to users.

## Plain-Text Output of the Core CLI

The `gt` binary serves as the main entry point for the Gas Town CLI. In [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go), the `main()` function delegates to `cmd.Execute()`, which leverages the **Cobra** framework (`github.com/spf13/cobra`) for command handling.

All user-facing subcommands write output using standard Go formatting functions such as `fmt.Fprint`, `fmt.Println`, or `slog`. This produces tables, colored status messages, and interactive prompts designed for terminal consumption. No JSON encoding is performed for these commands, making the output immediately human-readable but requiring text parsing for automation purposes.

## JSON Wire-Format in the Proxy Client

The exception to the plain-text rule occurs in `gt-proxy-client` when specific environment variables are configured. When `GT_PROXY_URL`, `GT_PROXY_CERT`, `GT_PROXY_KEY`, and `GT_PROXY_CA` are set, the client does not execute the real binary directly. Instead, it forwards commands to the proxy server via HTTP POST requests to `/v1/exec`.

The communication protocol uses a JSON envelope defined in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go):

```go
type execResponse struct {
    Stdout   string `json:"stdout"`   // Captured STDOUT from the real command
    Stderr   string `json:"stderr"`   // Captured STDERR from the real command
    ExitCode int    `json:"exitCode"` // Process exit status
}

```

The client sends an `execRequest` containing the argument vector (`argv`), receives the JSON response, extracts the `Stdout` and `Stderr` fields, writes them to the respective streams, and exits with the provided `ExitCode`. This JSON format is strictly internal to the proxy communication; end users still see only the plain-text content of the original command.

## Key Source Files

The output handling is implemented across these specific files:

- **[`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)**: Entry point that initializes Cobra and triggers plain-text output via `cmd.Execute()`
- **[`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go)**: Defines the `execResponse` struct and handles JSON unmarshaling before converting back to plain-text streams
- **[`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)**: Implements the server-side JSON protocol and returns the `execResponse` payload
- **[`internal/cmd/proxy_subcmds.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/proxy_subcmds.go)**: Supplies the list of allowed subcommands for proxy discovery

## Summary

- **Primary CLI (`gt`)**: Emits human-readable plain-text via Cobra's standard output methods in [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)
- **Proxy Server**: Logs in structured text format using `slog` at [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)
- **Proxy Client**: Uses internal JSON (`execResponse`) for wire communication in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go) but unwraps to plain-text for the user
- **Environment trigger**: Proxy JSON mode activates when `GT_PROXY_URL` and related TLS variables are set

## Frequently Asked Questions

### Does the gastown CLI output JSON for scripting purposes?

No, the `gt` command outputs human-readable plain-text by default. The only JSON involved is the internal wire format used by `gt-proxy-client` when communicating with the proxy server, which is transparently converted back to plain-text before display.

### Where is the output format defined in the source code?

The plain-text output format is implemented through the Cobra framework in [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go), utilizing standard Go formatting functions. The JSON structure for proxy communication is defined in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go) as the `execResponse` struct containing `stdout`, `stderr`, and `exitCode` fields.

### How does the proxy client handle command output?

The `gt-proxy-client` forwards commands to the proxy server via HTTP POST with a JSON payload. It receives an `execResponse` JSON object, then writes the `Stdout` and `Stderr` fields to the respective output streams and exits with the `ExitCode` value, effectively preserving the original command's plain-text output.

### Can I parse the output of gastown commands programmatically?

Since the standard `gt` commands output plain-text without a structured schema, you would need to parse the human-readable text. However, when using the proxy client, the underlying communication uses a predictable JSON structure defined in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go), though this is internal to the proxy mechanism.