The gist Gem: A Ruby Command-Line Tool for Uploading to GitHub Gist

What the gist Gem Does and Who It Is For

The gist gem solves a narrow problem: a developer has a file or a pipeline of text and wants it on GitHub Gist as a shareable URL, without switching to a browser. The README describes it as the best command-line gister, and the scope is exactly that. The tool wraps the GitHub Gist API, accepts one or more filenames or stdin, uploads the content, and returns the URL. It handles public and private gists, supports updating an existing gist by ID, and can copy the result directly to the clipboard.

The gem is a good fit for scripting workflows. A CI job that captures a test failure can pipe output to gist for a shareable link. A developer demoing code can run a single command instead of navigating to gist.github.com. The tool does not version gists locally, does not manage gist history, and provides no hosting independent of GitHub. If the Gist API is unavailable, the command returns nothing useful.

Two Authentication Flows and One Token File

The gem supports two OAuth paths. The default for github.com is the device-code flow: you run `gist --login`, the tool prints a URL and a short verification code, you visit the URL in a browser and type the code, and GitHub writes an access token back to `~/.gist`. This file contains only the token, a string of roughly 40 hex characters with an optional trailing newline.

The second path is the username-and-password exchange, which GitHub has deprecated but which may still work with GitHub Enterprise. For Enterprise installations, the `GITHUB_URL` environment variable redirects the tool to the internal host, and the token is stored in a file named `.gist.<protocol>.<server.name>` rather than `~/.gist`, keeping Enterprise and public GitHub credentials separate.

For environments that cannot use either interactive flow, you can create the token file manually. The README gives this example:

(umask 0077 && echo MY_SECRET_TOKEN > ~/.gist)

The `umask` flag restricts the file to your user account. Any line break inside the token string breaks authentication; the gem will return a Bad credentials error on the next listing call.

For GitHub Enterprise, export the base URL before running any gist command:

export GITHUB_URL=http://github.internal.example.com/

After a terminal restart or sourcing your shell config, the gem routes all requests to that host automatically.

Installing and Running Your First Upload

The gem installs through several paths depending on your platform. On any system with Ruby available:

gem install gist

On macOS with Homebrew:

brew install gist

On FreeBSD:

pkg install gist

On Debian and Ubuntu via apt:

apt install gist

Note that Debian renames the binary to `gist-paste` to avoid a naming conflict with another package in the distribution.

Before the first upload, authenticate:

gist --login

The device-code flow prints a URL and a short code. After you enter the code in your browser, the tool stores the returned token in `~/.gist` and confirms success with the settings URL. Once authenticated, uploading a file is a single command:

gist a.rb

The tool prints the gist URL to stdout. To upload multiple files at once:

gist a b c
gist *.rb

Both commands produce a single gist containing all specified files.

To add a description:

gist -d "Random rbx bug" a.rb

To make the gist private:

gist -p a.rb

To copy the result URL to the clipboard instead of printing it:

gist -c <a.rb

The Full Flag Set: stdin, Listing, Reading, and Updating

Reading from stdin is the default when no filename is given. You can force a specific filename for syntax highlighting with `-f`, which tells Gist what language to apply:

gist -f test.rb <a.rb

To paste directly from the clipboard:

gist -P

To open the new gist in a browser immediately after upload:

gist -o <a.rb

To copy an embeddable URL (for embedding gists in pages) rather than the direct URL, use `-e` instead of `-c`.

Listing gists uses the `-l` flag. Without an argument it lists the authenticated user's gists; with a username it lists that user's public gists:

gist -l : all gists for authed user
gist -l defunkt : list defunkt's public gists

To print the raw content of an existing gist to stdout:

gist -r 374130

To update an existing gist, pass the gist ID with `-u`:

gist -u 42f2c239d2eb57299408 test.txt

The ID appears in every gist URL on github.com. You can also set a default behavior with a shell alias. To always copy the URL to the clipboard after an upload, add this to `~/.bashrc`:

alias gist='gist -c'

The BROWSER environment variable controls which application `-o` opens. To use a specific browser:

export BROWSER=google-chrome

Using gist as a Ruby Library in Your Own Code

Beyond the CLI, the gem exposes a Ruby API that other programs can call. The simplest call uploads a string directly:

Gist.gist("Look.at(:my => 'awesome').code")

The method returns the URL of the created gist. It accepts several keyword options: `:access_token` for OAuth2 authentication when you do not want to rely on `~/.gist`, `:filename` to set the syntax-highlighting language, `:public` for a guessable URL, `:description` for a description, `:update` to modify an existing gist by URL or ID, `:copy` to copy the URL to the clipboard, and `:open` to launch a browser.

To upload multiple files in a single gist:

Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar")

If you need to force a user through the token acquisition process from inside a script:

Gist.login!

This takes the user through the OAuth flow and stores the resulting token in `~/.gist`. The README notes that the access_token must have the `gist` scope and may also require `user:email` for GitHub Enterprise. The library interface is useful for automation tools, report generators, or any workflow that creates gists programmatically rather than from a shell.

Limitations: Scope, Platform Notes, and GitHub Dependency

The tool does not work offline. Every upload, listing, and read operation calls the GitHub Gist API, so any outage on GitHub's side stops the gem from functioning. It cannot create repositories, manage code reviews, or interact with any other GitHub surface.

The device-code OAuth flow is tied to a specific OAuth application client ID registered by the gem's maintainers. GitHub Enterprise users who want to use this flow must create their own OAuth app and export its client ID as `GIST_CLIENT_ID`. The alternative `GIST_USE_USERNAME_AND_PASSWORD` variable enables the deprecated password flow, which GitHub has marked as legacy.

The repository has no GitHub releases, so version history and changelogs live in the RubyGems publish history rather than in a structured release page. For Bundler, the dependency declaration in a Gemfile is:

gem 'gist'

A real alternative for gist creation is the GitHub CLI (`gh`), which includes its own gist subcommand. The difference in approach is scope: `gh` is a broad GitHub interface covering pull requests, issues, and workflow runs, while `gist` is a single-purpose tool that does one thing and adds a Ruby library interface on top. Developers who already have `gh` installed for other tasks may not need a second install.

Maintenance and License

The gist gem is released under the MIT license. The repository is not archived, and the last push was on 2026-06-19. No GitHub releases are listed; new versions ship to RubyGems rather than through GitHub's release mechanism. The source is organized under a `lib/` directory with a `bin/` entry point and a `spec/` test suite. Bundler integration and a Gemfile are present in the repository.

Editorial conclusion

The gist gem is the right choice for developers who already use GitHub and want to create or update Gists from the terminal without opening a browser. It is the wrong tool for teams that need self-hosted snippet hosting, offline access, or versioned local storage of gists. Before adopting it, verify that your GitHub plan allows the device-code OAuth flow and that you can store a plain token in `~/.gist` without violating your organization's credential policy.

Frequently asked questions

Official sources

1. defunkt/gist on GitHub
2. Issues
3. License: MIT
4. Project website
5. README