carapace-sh/carapace-bin / skills/gh
gh
FlaggedUse when working with the GitHub CLI (`gh`) — authentication, repositories, pull requests, issues, releases, GitHub Actions (workflows, runs, caches), the gh API command, extensions, secrets and variables, search, gists, SSH/GPG keys, labels, rulesets, codespaces, browsing, configuration, aliases, JSON output formatting, and environment variables. Triggers on: "gh", "gh auth", "gh repo", "gh pr", "gh issue", "gh release", "gh run", "gh workflow", "gh api", "gh extension", "gh secret", "gh variable", "gh search", "gh gist", "gh label", "gh codespace", "gh browse", "gh status", "gh config", "gh alias", "gh completion", "gh ssh-key", "gh gpg-key", "gh ruleset", "gh cache", "gh org", "GH_TOKEN", "GH_REPO", "GH_HOST", "gh pr create", "gh pr checkout", "gh pr merge", "gh repo clone", "gh repo create", "gh issue create", "gh release create", "gh workflow run", "gh run list", "gh api graphql", "gh extension install", "gh secret set", "gh search repos".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.8 KB |
| references/actions.md | markdown | 10.1 KB |
| references/api.md | markdown | 6.5 KB |
| references/auth.md | markdown | 7.4 KB |
| references/browse-status.md | markdown | 5.6 KB |
| references/config.md | markdown | 8.3 KB |
| references/extension.md | markdown | 5.4 KB |
| references/gist-keys.md | markdown | 9.3 KB |
| references/issue.md | markdown | 9.9 KB |
| references/output-formatting.md | markdown | 5.2 KB |
| references/pr.md | markdown | 14.2 KB |
| references/release.md | markdown | 8.3 KB |
| references/repo.md | markdown | 10.3 KB |
| references/search.md | markdown | 10.7 KB |
| references/secret-variable.md | markdown | 7.0 KB |
references/output-formatting.md
View on GitHub# Output Formatting — JSON, jq, and Go Templates
How to format `gh` command output using `--json`, `--jq`, and `--template` flags.
## Overview
By default, `gh` commands output line-based plain text. Commands that support `--json` can output structured JSON, which can then be further formatted with `--jq` (jq query syntax) or `--template` (Go template syntax).
These flags are available on many list/view commands: `pr list`, `pr view`, `issue list`, `issue view`, `repo list`, `repo view`, `release list`, `release view`, `run list`, `run view`, `workflow list`, `cache list`, `label list`, `secret list`, `variable get`, `variable list`, `search *`, `extension search`, `auth status`, etc.
## `--json`
Output JSON with the specified fields. Pass a comma-separated list of field names.
```sh
$ gh pr list --json number,title,author
```
```json
[
{
"author": { "login": "monalisa" },
"number": 123,
"title": "A helpful contribution"
}
]
```
To discover available JSON field names for a command, omit the field argument:
```sh
$ gh pr list --json
```
When connected to a terminal, JSON output is automatically pretty-printed.
## `--jq`
Filter and select values using jq syntax. The `jq` utility does **not** need to be installed. Requires `--json` to be passed with field names.
```sh
# Select fields from an array
$ gh pr list --json author --jq '.[].author.login'
monalisa
codercat
# Complex filtering
$ gh issue list --json number,title,labels --jq \
'map(select((.labels | length) > 0)) # must have labels
| map(.labels = (.labels | map(.name))) # show only label names
| .[:3]' # select first 3
```
When connected to a terminal, jq output is automatically pretty-printed.
For jq query syntax, see <https://jqlang.github.io/jq/manual/>.
## `--template`
Format output using Go template syntax. Requires `--json` with field names.
```sh
# Simple template
$ gh pr list --json number,title,headRefName,updatedAt --template \
'{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}'
# Complex template with tables
$ gh pr view 3519 --json number,title,body,reviews,assignees --template \
'{{printf "#%v" .number}} {{.title}}
{{.body}}
{{tablerow "ASSIGNEE" "NAME"}}{{range .assignees}}{{tablerow .login .name}}{{end}}{{tablerender}}
{{tablerow "REVIEWER" "STATE" "COMMENT"}}{{range .reviews}}{{tablerow .author.login .state .body}}{{end}}
'
# Hyperlinks
$ gh issue list --json title,url --template '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}'
```
For Go template syntax, see <https://golang.org/pkg/text/template/>.
## Custom Template Functions
In addition to Go template standard library functions, gh provides:
| Function | Description |
|----------|-------------|
| `autocolor <style> <input>` | Like `color`, but only emits color to terminals |
| `color <style> <input>` | Colorize input using [mgutz/ansi](https://github.com/mgutz/ansi) |
| `join <sep> <list>` | Join values in a list using a separator |
| `pluck <field> <list>` | Collect values of a field from all items in the input |
| `tablerow <fields>...` | Align fields in output vertically as a table |
| `tablerender` | Render fields added by `tablerow` in place |
| `timeago <time>` | Render a timestamp as relative to now |
| `timefmt <format> <time>` | Format a timestamp using Go's `Time.Format` |
| `truncate <length> <input>` | Ensure input fits within length |
| `hyperlink <url> <text>` | Render a terminal hyperlink |
### Sprig Template Functions
The following [Sprig](https://masterminds.github.io/sprig/) library functions are also available:
| Function | Description |
|----------|-------------|
| `contains <arg> <string>` | Check if `string` contains `arg` |
| `hasPrefix <prefix> <string>` | Check if `string` starts with `prefix` |
| `hasSuffix <suffix> <string>` | Check if `string` ends with `suffix` |
| `regexMatch <regex> <string>` | Check if `string` has matches for `regex` |
## `gh api` Formatting
The `gh api` command also supports `--jq` and `--template` for formatting API responses. Unlike other commands, `gh api` does not require `--json` — the response is already JSON.
```sh
$ gh api repos/{owner}/{repo}/issues --jq '.[].title'
$ gh api repos/{owner}/{repo}/issues --template \
'{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'
```
See [api.md](api.md) for `gh api` details.
## Common Patterns
### Extract a Single Field
```sh
$ gh pr list --json number --jq '.[].number'
123
124
```
### Filter and Transform
```sh
# PRs with more than 0 labels, showing only label names
$ gh issue list --json number,title,labels --jq \
'map(select((.labels | length) > 0)) | map(.labels = (.labels | map(.name)))'
```
### Table Output
```sh
$ gh pr list --json number,title,headRefName,updatedAt --template \
'{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}'
```
### Hyperlinks
```sh
$ gh issue list --json title,url --template \
'{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}'
```
## Related
- For the `gh api` command, see [api.md](api.md).
- For environment variables affecting output (`NO_COLOR`, `CLICOLOR`, `GH_FORCE_TTY`), see [config.md](config.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |