# Add JSON Output to a Go Command-Line Tool

Yes. An agent adds an -o json mode to your Go CLI, with a documented schema, tests that decode the output, and a pull request that keeps the text output unchanged.

[Run this on Rush](https://cloud.getrush.ai/run/add-json-output/go-cli/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how output is produced before it adds a format. In a tool like rakyll/hey, `hey.go` declares the flags with the standard `flag` package: `-n`, `-c`, `-q`, `-z`, the request flags, and `-o`, whose usage text says a summary is printed by default and `"csv" is the only supported alternative`. The value goes into `requester.Work.Output`, and `requester/print.go` turns it into a `text/template`: `newTemplate` picks `defaultTmpl` for an empty string, `csvTmpl` for `csv`, and otherwise parses the flag's value itself as a template, an undocumented path. The function map already has a `jsonify` helper that calls `json.Marshal`, but no template uses it, which tells the agent someone meant to get here.

The data is in `requester/report.go`. The exported `Report` struct holds the summary (`AvgTotal`, `Fastest`, `Slowest`, `Average`, `Rps`, `Total`, `NumRes`, `SizeTotal`, `SizeReq`), the per-phase averages and extremes for DNS, connection, request write, response wait and response read, `ErrorDist` and `StatusCodeDist` maps, `LatencyDistribution` (the 10th to 99th percentiles) and `Histogram` (buckets with `Mark`, `Count` and `Frequency`), and the raw per-request slices (`Lats`, `ConnLats`, `DnsLats`, `ReqLats`, `ResLats`, `DelayLats`, `Offsets`, `StatusCodes`), capped at the `maxRes` constant. `Total` is a `time.Duration`, which `encoding/json` would write as nanoseconds. `go.mod` says `go 1.24.0` with one dependency, `golang.org/x/net`; the tests are `hey_test.go` for header and auth parsing and `requester/requester_test.go` (`TestN`, `TestQps`, `TestRequest`, `TestBody`) against `httptest` servers; `.github/workflows/go.yml` runs `go build -v ./...` and `go test -v ./...`.

The agent adds `json` as a named case beside `csv`. Rather than a template, `report.print` encodes a value with `encoding/json` when the output is `json`: a `jsonReport` struct with snake_case tags that carries the summary, the phase statistics, `latency_distribution`, `histogram`, `status_code_distribution` and `error_distribution`, with `total` rendered in seconds as a float to match every other duration in the report, and without the per-request slices, which can be a million entries and already have the CSV format. A second mode, `json-full`, includes them for people who want to post-process. The usage string in `hey.go` and the `-o` section of `README.md` are updated, and the comment block at the top of `print.go` that documents the two formats gets a third entry listing every field.

It writes `requester/print_test.go`: a `Work` with `Output: "json"` against an `httptest` server, its writer replaced by a `bytes.Buffer` the way the existing tests reach into `Work`, decoded with `json.Unmarshal` into a map, asserting `num_res` equals `N`, that `status_code_distribution` has a `200` key, and that `histogram` has the eleven buckets `report.histogram` builds. A `-o json-full` case checks `lats` has `N` entries. Then `gofmt -l .`, `go vet ./...` and `go test ./...` run in the sandbox and their output goes in the pull request. The agent also notes that `go.yml` installs Go 1.21 while `go.mod` requires 1.24.0 and relies on the toolchain download, and leaves that as a sentence in the pull request rather than a change.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a JSON output format to this Go command-line tool. Read how the -o flag is parsed and how the report is rendered first, and reuse the existing report data rather than computing anything new. Add -o json that writes one JSON object with the summary, per-phase statistics, latency percentiles, histogram, status code and error distributions, with durations in seconds as floats and snake_case field names, and -o json-full that also includes the per-request arrays. Leave the default text output and the csv output byte-for-byte unchanged. Update the usage text and the README. Write a test that runs the tool against an httptest server with each JSON mode and decodes the output. Run gofmt, go vet and go test and open a pull request that shows a sample of the JSON.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that changes `requester/print.go` (the `json` and `json-full` cases and the encoder), `requester/report.go` (the tagged output struct and a conversion from `Report`), `hey.go` (the usage text) and `README.md`, and adds `requester/print_test.go`. The description shows one `-o json` document from the test server, lists every field with its unit, and quotes the `go test ./...` and `go vet` output from the sandbox.

The run's record keeps each command with its output, including a diff of the default text output before and after the change (the agent runs the tool against the same test server on both commits) to show the summary format did not move.

Before merging, a reviewer checks the field names against whatever already consumes the CSV, decides whether `histogram` marks should be seconds or milliseconds for their dashboards, and confirms that `-o json` with `-z` (a duration run) is covered, since `n` is then `math.MaxInt32` and `num_res` is the only honest count.

## Run it on every Linear issue labelled output

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `config.labels` set to `output`, starts one run per issue that asks for a new format or field, with the issue text added after the prompt. The run reads the issue, makes the change and opens a pull request that links it.

From your own server, the same work is one `POST /o/{org}/sessions` with this body and the repository in `resources`; a webhook on the API key reports `run.completed` with the `session_url` to read the pull request link.

## Why run it on Rush?

Adding a format to a CLI touches the flag parser, the renderer, the docs and the tests at once, and the easy version (`jsonify` the whole `Report`) writes nanosecond durations and a million-element array that no consumer wants. The agent reads the existing template path and the struct before choosing what to serialise, and proves the text and CSV outputs did not change by running the tool against the same server on both commits.

The sandbox runs `go test ./...` with the module's own Go version and keeps the output in the record, so the pull request arrives with its evidence rather than a promise. Several tools, or several formats, can be done at the same time in separate sandboxes.

## Frequently asked questions

### Will the existing text or CSV output change?

No. The new modes are new cases; the default template and the CSV template are not edited, and the run compares the text output before and after on the same test server. The prompt makes this a hard requirement.

### Why are the per-request arrays left out of -o json?

The report caps them at a million entries each, and eight such arrays make a document nobody reads by eye. `-o json-full` includes them for post-processing, and the CSV format already carries the same rows one per line.

### What about the undocumented custom-template path?

It keeps working: any `-o` value that is not `csv`, `json` or `json-full` is still parsed as a `text/template`, and the `jsonify` helper remains for people who use it. The pull request mentions it rather than documenting it, which is a maintainer's call.

### Does it handle a run cut short with -z or Ctrl-C?

Yes. The report is finalised from whatever results arrived, and `num_res` is the count of those, so a `-z 10s` run produces a complete JSON document with the requests that finished. The test covers a fixed `-n` run; a duration run is noted for the reviewer.

## More Go CLI jobs

- [Add a Man Page to a Go CLI](https://getrush.ai/run/add-man-page/go-cli/)
- [Add a Nix Flake to a Go CLI](https://getrush.ai/run/add-nix-flake/go-cli/)
- [Add a Progress Bar to a Go Command-Line Tool](https://getrush.ai/run/add-progress-bar/go-cli/)

## The same job on other stacks

- [Add JSON Output to a Rust CLI](https://getrush.ai/run/add-json-output/rust-cli/)

## More jobs like this: Hand off a long task

- [Publish a TypeScript Library to JSR Alongside npm](https://getrush.ai/run/add-jsr-publishing/typescript-library/)
- [Add JWT Authentication to an Actix Web API](https://getrush.ai/run/add-jwt-auth/actix/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
