---
name: "gt-formatting"
section: "1"
platform: "linux"
package: "gitea-cli"
version: "1.0.0-1"
release: "Arch Linux 2026-11-07"
platforms: ["linux"]
url: "https://carta.tech/man/gt-formatting"
---

# gt-formatting(1)

JSON and CSV output with --json, --jq and --csv

## NAME

gt-formatting - JSON and CSV output with --json, --jq and --csv

## SYNOPSIS

**gt formatting**

## DESCRIPTION

gt prints text for people by default. Scripts should use JSON or CSV: the columns and wording of text output may change between releases.

```
  --json             print every field
  --json FIELDS      print only the comma-separated FIELDS, such as --json number,title
  -q, --jq EXPR      filter the JSON with a jq expression; implies --json
  --csv              print every field as CSV
  --csv FIELDS       print only the comma-separated FIELDS as CSV, such as --csv number,title
```

The JSON FIELDS section of a command's help lists its fields, which --csv selects too, and shell completion offers them after --json and --csv. An unknown field reports the available ones. A word after --json or --csv is read as an argument only when the command takes no other, as in gt release view --json v1; write --json=FIELDS to make it a field list.

\--csv prints a header row of the field names, then one row per item; a command that returns one item prints one row. Strings print as they are, null as an empty cell, and numbers, booleans, objects and arrays as compact JSON. --csv cannot be combined with --json or --jq.

\--jq runs inside gt, so jq does not need to be installed. String results print without quotes:

```
  $ gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
```

Some fields cost extra requests, such as the reviewers of pr list, the blocked\_by and blocks of issue view and issue edit, and the visibility of org member list. gt makes them only when the output includes the field: --json or --csv names it, or selects every field and the --jq expression names it. An expression that reaches such a field without naming it, as to\_entries does, sees it empty; name the field in --json instead.

Commands that take several arguments, such as issue close or milestone issue add, print an object for one argument and an array of the successful results for several. A script that needs one shape passes one argument per call, or several and reads the array, such as with --jq '.\[\]'.

On a terminal, JSON is indented and colored; otherwise each value prints on one line. Commands that return no resource, such as deletes, reject --json and --csv.

## SEE ALSO

**[gt(1)](/man/gt/1.md)**