.nh
.TH "GT-FORMATTING" "1" "Nov 2026" "gitea-cli" "gitea-cli Manual"

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


.SH SYNOPSIS
\fBgt formatting\fP


.SH 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.

.EX
  --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
.EE

.PP
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.

.PP
--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.

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

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

.PP
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.

.PP
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 '.[]'.

.PP
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.


.SH SEE ALSO
\fBgt(1)\fP