Inspect GitHub Gists Safely with gh gist view

You will finish with a small, repeatable set of commands for reading a GitHub gist from a Linux shell, selecting one file, listing the files it contains, and obtaining raw content when rendered output is not suitable. The examples use GitHub CLI 2.87.3, installed here from the gh package.

Allow about ten minutes. You need the gh command, network access to GitHub, and permission to read the gist. No elevated privileges are required. This guide only views content; it does not create, edit or delete a gist.

1. Check the installed command

Confirm which executable will run and record the local version. These are ordinary read-only commands:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3

Ask the subcommand for its local contract as well:

$ gh gist view --help
View the given gist or select from recent gists.

USAGE
  gh gist view [<id> | <url>] [flags]

Checkpoint: the installed manual documents --filename, --files, --raw and --web. Keep examples aligned with this output because command-line options can vary between package versions.

2. View a gist by ID or URL

Pass a gist ID or its URL. Use a real value in place of GIST_ID; the placeholder is deliberately not a command you should paste unchanged:

$ gh gist view GIST_ID
$ gh gist view https://gist.github.com/USER/GIST_ID

The command renders the gist contents for terminal reading. A successful view normally exits with status 0. Because the exact body depends on the gist, verify the status directly when scripting:

$ gh gist view GIST_ID >/tmp/gist-view.txt
$ status=$?
$ printf 'gh gist view exit status: %s\n' "$status"
gh gist view exit status: 0

The temporary file is local output, not a copy written back to GitHub. Remove it when it is no longer needed if the gist contains private or sensitive material:

$ rm -- /tmp/gist-view.txt

Warning: viewing a private gist still exposes its contents to your terminal, shell history if you put sensitive values in commands, and any process or user with access to a file you save. Do not paste secrets into a shared terminal.

3. List the files before choosing one

A gist can contain several files. Ask for names only when you need to discover its shape:

$ gh gist view GIST_ID --files
README.md
script.sh

The names above are illustrative. Your output will be different. This option does not print each file's contents, which makes it a useful checkpoint before requesting a large or unexpected file.

Choose the exact name printed by --files and pass it to --filename:

$ gh gist view GIST_ID --filename script.sh
#!/usr/bin/env bash
printf '%s\n' 'gist script'

Quote a filename containing spaces or shell punctuation:

$ gh gist view GIST_ID --filename 'notes for review.txt'

If the name is wrong, expect an error and a non-zero exit status. Do not infer the name from a local file or guess a path; gist filenames are selected from the gist itself.

4. Retrieve raw content for a pipeline

Use --raw when you need the file content without terminal rendering. Combine it with --filename when the gist has more than one file:

$ gh gist view GIST_ID --filename script.sh --raw
#!/usr/bin/env bash
printf '%s\n' 'gist script'

For a read-only inspection pipeline, send the result to a command that does not execute it:

$ gh gist view GIST_ID --filename script.sh --raw | sed -n '1,20p'

Do not pipe untrusted gist content to a shell, interpreter or installer. In particular, avoid patterns such as gh gist view ... --raw | sh. Raw output is data; gh does not make it safe to execute.

5. Open the gist in a browser when terminal output is not enough

Use --web to ask the operating system to open the gist in its browser:

$ gh gist view GIST_ID --web

This requires a usable graphical browser or browser integration in the current environment. It is not a file download and it does not edit the gist. On a headless SSH session, use the ID or URL with the terminal options instead.

6. Handle authentication and input errors

A gist ID or URL is required in a non-interactive shell. Running the command without one on this machine produces gist ID or URL required when not running interactively and exits 1. Supply an explicit identifier in scripts:

$ gh gist view
gist ID or URL required when not running interactively
$ printf '%s\n' "$?"
1

A private gist may require authentication. Check the CLI session without printing a token:

$ gh auth status

If the command reports that authentication is required, stop there and use your normal approved gh auth login process. Do not put a token in the gist ID, a shell variable shown in shared logs, or a command copied into a ticket.

Exit status 0 means the command succeeded. Status 1 means an error, status 2 means the command was cancelled, and status 4 means authentication is required according to the installed manual. Treat any other non-zero result as a failure and preserve the diagnostic text for investigation.