---
sidebar_position: 5
---

# Output and scripting

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

## JSON

`--json` prints every field of the result, `--json FIELDS` only the comma-separated
fields you list:

```bash
gt issue list --json
gt pr view 123 --json number,title,state
```

The **JSON FIELDS** section of a command's `--help` lists its fields, and shell completion
offers them after `--json`. An unknown field reports the available ones. Commands that
return no resource, such as deletes, reject `--json`.

`--jq` (`-q`) filters the JSON with a [jq](https://jqlang.org) expression and implies
`--json`. It runs inside gt, so jq does not need to be installed. String results print
without quotes:

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

Some fields cost extra requests, such as the reviewers of `gt pr list`. gt makes them only
when the output includes the field: `--json` names it, or `--json` 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.

On a terminal, JSON is indented and colored; otherwise each value prints on one line. gt
does not prompt while it prints JSON; `--interactive` allows prompts anyway.
`gt help formatting` describes all of this.

## Piped output

JSON and other results go to stdout. Diagnostics, prompts and the messages that confirm a
change go to stderr, so they never end up in the data a script reads.

Piped or redirected, lists print as tab-separated values without a header row, ready for
`cut` or `awk`:

```bash
gt issue list --kind all --milestone v1.0 | cut -f1,2
```

Color settings never color piped output. Only a command's own `--color always` does, such
as `gt pr diff --color always`.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success, including an empty list |
| 1 | The command failed |
| 2 | Usage error: an unknown command or flag, or a missing or invalid argument |
| 3 | Canceled: a declined confirmation, a prompt left with Esc or Ctrl-D, or a timeout |
| 4 | Authentication is missing or was rejected |
| 8 | `gt pr checks`: some checks are still pending |
| 130 | Interrupted with Ctrl-C, also at a prompt |

A command may document further codes in its help. `gt auth status`, for example, exits
with 4 when there is no account or a credential is missing or rejected; with `--json` it
exits with 0 either way and reports the problem in its output.

## The API

`gt api` sends an authenticated request to the instance's API, for what no command covers
yet. The endpoint is a path under `/api/v1`, and `{owner}` and `{repo}` take the current
repository:

```bash
gt api user --jq .login
gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
gt api user/repos --paginate --jq '.[].full_name'
```

A response outside 2xx prints its body, then fails. `gt auth token` prints the token gt
uses, for tools that call the API themselves.

## Aliases

An alias is a shortcut that expands to a gt command with its arguments:

```bash
# gt il runs gt issue list --label bug
gt alias set il "issue list --label bug"
# $1 takes the first argument: gt review 13 runs gt pr review 13 --approve
gt alias set review 'pr review $1 --approve'
```

`$1`, `$2` and so on take the arguments in that position; other arguments follow the
expansion, so `gt il --state all` runs `gt issue list --label bug --state all`. Aliases never
run a shell, and a built-in command always wins over an alias of the same name.
`--clobber` replaces an existing alias, `gt alias list` lists them and `gt alias delete`
removes one. They are kept in `config.yml`.