Create a Safe, Shareable Gist with gh gist create

You have a snippet, a log or a config and you want a link to it in the next thirty seconds. gh gist create uploads local text files, or standard input, and hands back a URL. Allow about five minutes if gh is already authenticated, or ten if you need to check authentication and inspect the files first.

The examples use GitHub CLI 2.87.3, installed on the reference machine in February 2026.

Before you start

• You need the gh command. Plus a GitHub account that can create gists, and files whose contents you have checked.
• No root access. The command changes remote GitHub state, so treat it as a publishing action.
• Nothing sensitive. This command sends the contents to GitHub. Leave out passwords, private keys, access tokens, customer data and anything else that should not leave the machine.

1. Check the installed command

Confirm which executable will run and inspect the local version and flags:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh gist create --help

The installed manual accepts filenames, shell patterns, or - for standard input. The options:

• --desc sets a description.
• --filename names content that arrives on standard input.
• --public makes a listed gist.
• --web opens the created gist in a browser.

2. Inspect the file before uploading

Use an explicit path and review the content. These commands do not contact GitHub:

$ FILE='/path/to/example.txt'
$ test -f "$FILE" && printf 'file exists: %s\n' "$FILE"
file exists: /path/to/example.txt
$ sed -n '1,80p' "$FILE"

A local file's name becomes the gist file's name. Do not rely on a broad wildcard until you have checked what it expands to.

3. Create a secret gist from one file

Pass the file and an optional description. Omitting --public uses the default secret visibility:

$ gh gist create "$FILE" --desc "Example text for a shell guide"
- Creating gist example.txt
✓ Created secret gist example.txt
https://gist.github.com/ACCOUNT/GIST_ID

The final line is the URL returned by gh. Copy it somewhere appropriate, but keep it out of public issues and logs if the contents are sensitive. If you lose the URL, list your recent gists after authentication:

$ gh gist list --secret --limit 10

4. Create a listed gist deliberately

Use --public only after checking the content and deciding it may be publicly discoverable:

$ gh gist create --public "$FILE" --desc "Public example text"
- Creating gist example.txt
✓ Created public gist example.txt
https://gist.github.com/ACCOUNT/GIST_ID

5. Put several files in one gist

List each file explicitly when the set is small and important:

$ gh gist create README.txt script.sh --desc "Two-file example"
- Creating gist README.txt
✓ Created secret gist README.txt
https://gist.github.com/ACCOUNT/GIST_ID

Shell patterns are also accepted. Expand them first if there is any risk of matching a secret or an unrelated file:

$ printf '%s\n' *.md *.txt
$ gh gist create *.md *.txt --desc "Markdown notes"

An unmatched pattern can stay literal in common shells, which then causes a file-read error. The preview command makes an empty match obvious before the upload.

6. Send standard input with a chosen filename

Use - when the content comes from a pipeline. Without --filename, gh uses a generated text filename such as gistfile0.txt:

$ printf '%s\n' 'temporary report' | gh gist create - --filename report.txt --desc "Generated report"
- Creating gist report.txt
✓ Created secret gist report.txt
https://gist.github.com/ACCOUNT/GIST_ID

This suits command output. The installed implementation accepts text content and rejects binary content; use a file-oriented transfer method for binary data.

7. Open the result in a browser if you want

Add --web and gh opens the created gist after the upload:

$ gh gist create "$FILE" --desc "Browser check" --web
- Creating gist example.txt
✓ Created secret gist example.txt
Opening https://gist.github.com/ACCOUNT/GIST_ID in your browser.

Common traps

• Authentication missing. gh reports an authentication error and the manual assigns exit code 4. Run the normal gh auth login flow, then retry the original command. Do not put a token on the command line, where it can enter shell history.
• Bad input file. A missing, unreadable or binary file fails before a gist is created. Fix the path or choose text input, then rerun.
• API rejection. Check the account's gist permission and the authentication state.
• Uncertain retry. A successful retry creates another gist. Check the URL or gh gist list before repeating.

The manual also records exit code 1 for an error and 2 when the command is cancelled. In scripts, test the status rather than searching human-readable output:

if URL=$(gh gist create "$FILE" --desc "Automated example"); then
    printf 'created: %s\n' "$URL"
else
    status=$?
    printf 'gist creation failed with status %s\n' "$status" >&2
    exit "$status"
fi