table of contents
| GT-FORMATTING(1) | gitea-cli Manual | GT-FORMATTING(1) |
NAME¶
gt-formatting - JSON, CSV and template output with --json, --jq, --template 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
--template TEXT format the JSON with a Go template; 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, issue edit, pr view and pr 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 '.[]'.
--template renders the JSON through a Go template (text/template), as gh does, so a result can be laid out for people or for another program without jq. The data is the JSON that --json would print: an array for a list, an object for one item. A template prints exactly what it says, so end a line with {{"\n"}}. It cannot be combined with --jq or --csv, and commands that take their own --template, issue create, repo create and project create, keep it for their templates.
$ gt issue list --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'
$ gt pr list --json number,title,author --template '{{range .}}{{tablerow .number .title .author}}{{end}}{{tablerender}}'
$ gt release view v1 --template '{{.tag}}: {{join ", " (pluck "name" .assets)}}{{"\n"}}'
Besides the functions of Go's text/template, these are available:
join SEP LIST join the values of a list
pluck FIELD LIST collect one field of every object of a list
tablerow CELLS... add a row to a table; tablerender prints the table, columns aligned
timeago TIME a timestamp as "about 3 hours ago"; timefmt LAYOUT TIME uses Go's layout
truncate N TEXT cut TEXT to N columns, ending in …
color STYLE TEXT paint TEXT: black, red, green, yellow, blue, magenta, cyan or white,
with +b bold, +d dim, +u underline or +h bright, as in green+b;
autocolor paints only on a terminal that shows color
hyperlink URL TEXT a link on a terminal that supports them, else TEXT
contains PART TEXT, hasPrefix PREFIX TEXT, hasSuffix SUFFIX TEXT, regexMatch PATTERN TEXT
Numbers print in full, as in {{.number}} for 123456789. Text that the server sent has its control characters removed on a terminal before the template sees it. A field that an item does not have prints as <no value>.
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, --template and --csv.
Previews: every command that changes things only on Gitea, such as issue close, pr merge, release create and repo delete, takes --dry-run; commands that also change the clone or gt's settings, such as pr create, repo clone and config set, do not. It sends the reads the command needs, withholds every write request, asks nothing, as with --no-input, and prints the requests instead, as {"dry_run":true,"requests":[{"method":"PATCH","url":"...","body":{...}}]} with --json or --jq, else as one line per request; what the command would print about the writes is held back, and passwords, tokens and secrets in a request are shown as [REDACTED]. Nothing changes on Gitea or locally, and since nothing is sent, a preview cannot show a write that Gitea would refuse.
Compatibility: scripts may rely on the JSON that --json and --jq select, not on text or the order of keys. gt only adds fields and commands: a field is never removed or renamed, and it keeps its JSON type, though a field may become null where it had no value. A field that is going away is documented as deprecated for at least one release first. Fields that vary, such as those of gt config get, are the exception and say so in their help. gt schema prints every command's fields with their types, as JSON:
$ gt schema issue list
$ gt schema --jq '.commands[] | select(.command == "gt pr view") | .fields[].name'
SEE ALSO¶
| Nov 2026 | gitea-cli |