gh gist create: Usage, Options & Common CI Errors

Create a gist from files or piped output - public or secret.

gh gist create makes a new gist from one or more files or from stdin. Gists default to secret (unlisted); --public makes them discoverable.

What it does

gh gist create <files...> uploads files as a gist and prints its URL. With - it reads content from stdin (handy for piping logs), --public makes the gist public, and --desc adds a description. Secret gists are not searchable but are reachable by anyone with the URL.

Common usage

# Create a secret gist from a file
gh gist create notes.md

# Public gist with a description, multiple files
gh gist create script.sh README.md --public --desc "Demo"

# From stdin (pipe CI output into a gist)
some-command | gh gist create - --desc "build log"

Common error in CI: missing gist scope / empty content

gh gist create fails with HTTP 403 or "error creating gist" when the token lacks the gist scope, or with "a gist file cannot be blank" when stdin is empty. Fix: use a token that includes the gist scope (the default Actions GITHUB_TOKEN cannot create gists - supply a PAT with gist); ensure the piped command actually produced output before creating a stdin gist. Never put secrets in a public gist - prefer secret gists or artifacts for sensitive logs.

Key options

Related guides