GT-FORMATTING(1) gitea-cli Manual GT-FORMATTING(1)

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

gt formatting

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.

gt(1)

Nov 2026 gitea-cli