defunkt/gist: The Ruby CLI That Pipes Terminal Output to gist.github.com
Potentially the best command line gister.
At a glance
- What is it?
- The gist gem turns a file, a glob or STDIN into a GitHub Gist without leaving the shell. It is a small, MIT-licensed Ruby tool with a device-code login flow, and its main constraint is that it is bound to GitHub's API and to Ruby's packaging story.
- Who is it for?
- Adopt defunkt/gist if you already have Ruby or a package manager that ships it, and you want a one-command path from a local file or STDIN to a gist URL. Do not adopt it if you need GitLab snippets, a non-GitHub host without an Enterprise endpoint, or a tool with a documented release history, since the repository has no published releases.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- defunkt/gist3,808 ★ · +1
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| defunkt/gist | 3.8k | 3.8k |
1 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What the gist command actually removes from your workflow
Sharing a snippet normally means opening a browser, pasting code into a form, picking a filename so syntax highlighting works, and copying the URL back. defunkt/gist collapses that into one shell command. The README's own summary is blunt: it "provides a `gist` command that you can use from your terminal to upload content to https://gist.github.com/".
The audience is narrow and identifiable. It is for people who already live in a terminal: Ruby developers, sysadmins pasting logs, anyone who wants to hand a colleague a URL for a stack trace rather than an attachment. It is not a general-purpose file-sharing service and it does not pretend to be one. The whole surface is upload, update, list, read, and a few clipboard and browser conveniences.
The design assumption worth noting is that GitHub is the storage layer. There is no local cache, no sync daemon, no offline mode described in the README. If GitHub is unreachable, the command has nothing to fall back on.
How gist talks to GitHub: token file, environment variables, one API
Every invocation resolves to an access token, then makes an HTTP call to the GitHub API. The token lives in a file. For public github.com that file is `~/.gist`; the README states the returned access_token "is stored in `~/.gist` and used for all future gisting".
The file is not JSON and it is not a config file with keys. It contains only the token, roughly 40 hex characters, with an optional trailing newline. That simplicity is also the failure mode: the README warns that if the file contains line breaks you may see `Error: Bad credentials` when you run `gist -l`.
Host selection is done with an environment variable rather than a flag. Exporting `GITHUB_URL` points the tool at a GitHub Enterprise instance, and the token then moves to a host-specific filename derived from the protocol and server name, for example `~/.gist.http.github.internal.example.com`. The README is explicit that switching back to public GitHub requires `unset GITHUB_URL`, and that setting the variable to the public URL will not work. That is an easy trap for anyone juggling two hosts in one shell session.
Authentication itself has two paths. The device-code OAuth flow is the default for github.com. The username-and-password exchange is described as deprecated by GitHub but retained as the default for GitHub Enterprise. For Enterprise, the device-code flow can be enabled by creating an OAuth app and exporting `GIST_CLIENT_ID`.
Installing gist and publishing your first file
There is no source build step in the README. You install through whatever package manager you already have. With Ruby present, the gem is the direct route:
gem install gistOn macOS the README points to Homebrew with `brew install gist`, on FreeBSD to `pkg install gist`, and on Ubuntu or Debian to `apt install gist`. One caveat matters on Debian: the README notes that Debian renames the binary to `gist-paste` to avoid a name conflict, so the command you type differs from the command everywhere else.
Bundler users add it to a Gemfile instead:
source :rubygems
gem 'gist'Before the first upload you log in. The device-code flow prints a URL and a code, and you complete the exchange in a browser:
gist --loginThe README's sample output shows `Please sign in at https://github.com/login/device` followed by a code in the form `XXXX-XXXX`, and on success a URL under `github.com/settings/connections/applications/`. Once that succeeds, uploading is a single argument:
gist a.rbMultiple files go in one gist with `gist a b c` or `gist *.rb`. If you have no file at all, the command reads STDIN, and `-f` supplies the filename that drives syntax highlighting: `gist -f test.rb <a.rb`. The flags most people reach for are `-p` for private, `-d "description"` to attach a description, `-c` to copy the resulting URL to the clipboard, and `-o` to open it in a browser. Existing gists are updated in place with `gist -u GIST_ID FILE_NAME`, and `gist -r GIST_ID` prints a gist back to STDOUT.
Where gist stops being the right tool
The hardest boundary is hosting. This tool speaks to GitHub and to a GitHub Enterprise endpoint you configure. If your organization standardizes on GitLab snippets or an internal paste service with a different API, there is no adapter here and the README describes none.
The second boundary is authentication friction. The username-and-password flow is deprecated by GitHub, and the README says so. On public github.com you should expect the device-code flow, which means an interactive browser step. That is fine on a laptop and awkward on a headless build machine. The README does address the headless case indirectly: you can create `~/.gist` yourself by pasting a token with the `gist` scope, and it gives a one-liner using `umask 0077` so the file is only readable by your user account. Note that this is a manual step, not something the tool does for you.
A third limitation is operational rather than technical. The repository has no published GitHub releases, so there is no changelog to tell you what changed between versions or what a safe upgrade path looks like. The README documents the current flag set and login flows; it does not document rollback, version pinning, or a deprecation schedule for the username-and-password path beyond calling it deprecated.
Finally, the README's own troubleshooting note about clipboard and browser integration is telling: "If clipboard or browser integration don't work on your platform, please file a bug or (more ideally) a pull request." The `-c`, `-e`, `-o` and `-P` flags depend on platform integration that the maintainers do not claim to have solved everywhere.
gist as a Ruby library versus shelling out to the binary
The gem is not only a CLI. The README shows it used from inside Ruby code, which is the real alternative to piping through the executable: call the library instead of spawning a process and parsing a URL from stdout.
The simplest call is `Gist.gist("Look.at(:my => 'awesome').code")`. For anything beyond that you pass options, and the README enumerates them: `:access_token` to authenticate (defaulting to reading `~/.gist`), `:filename` to change syntax highlighting (default `a.rb`), `:public`, `:description`, `:update` to update an existing gist by URL or id, `:copy` and `:open` for the same clipboard and browser behaviour as the flags. Multiple files in one gist go through a separate entry point:
Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar")There is also `Gist.login!`, which forces the user through the OAuth token acquisition and stores the result in `~/.gist`. If you are writing a tool that needs to publish snippets on a user's behalf, this is the difference that matters: `Gist.login!` gives you a way to obtain credentials from within your own program rather than telling the user to install a separate binary and run `gist --login` first. The README also notes the scope requirement: the token must have the `gist` scope and may also require `user:email`.
Configuration habits the README endorses
There is no config file with defaults. The README's answer to "I always want the URL copied" is a shell alias, shown as `alias gist='gist -c'` in `~/.bashrc` or the equivalent. Browser selection is an environment variable, not a flag: `export BROWSER=google-chrome`.
This is a deliberate minimalism, and it has a cost. If you want different defaults per project, or a per-directory setting, the tool offers nothing, and you are back to shell wrappers. The upside is that there is no hidden state beyond the token file, which makes the behaviour easy to reason about when something breaks.
One practical consequence of the token-file design: the file location itself encodes the host. Public GitHub uses `~/.gist`; Enterprise uses `~/.gist.<protocol>.<server.name>[.<port>]`. If you work against several servers, the README's suggested workaround is scripts that set `GITHUB_URL` and then run `gist`, remembering to `unset` it afterwards. That is a workaround, not a feature, and it is the kind of thing worth writing down before a teammate spends an afternoon on a `Bad credentials` error.
Licence and the cost of keeping gist working
The repository is licensed under MIT, with `LICENSE.MIT` at the top level. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the licence and copyright notice are preserved. This is not legal advice; read the file itself if the distinction matters to you.
The maintenance picture is limited by what the repository shows. The repository is not archived, and the last push was on 2026-06-19. The repository has no published GitHub releases, so there is no release cadence to reason about and no version history to check for breaking changes. Treat the README as the specification and pin whatever version your package manager gives you.
Upgrade cost is mostly external. The tool's behaviour depends on GitHub's OAuth and API surfaces, and the README already flags one of them as deprecated. A future change on GitHub's side does not require a new gem version to break your workflow. That is the real maintenance risk here, and it sits outside the repository.
Editorial conclusion
Adopt defunkt/gist if you already have Ruby or a package manager that ships it, and you want a one-command path from a local file or STDIN to a gist URL. Do not adopt it if you need GitLab snippets, a non-GitHub host without an Enterprise endpoint, or a tool with a documented release history, since the repository has no published releases. Before relying on it, verify three things in your own environment: that gist --login completes against your host, that ~/.gist is written with mode 0077 as the README's umask example intends, and that the token you issue carries the gist scope plus user:email if you use GitHub Enterprise.
Frequently asked questions
What is a gist, and what does the defunkt/gist command do with one?
A gist is a piece of content hosted at gist.github.com. The gist gem provides a command that uploads content from your terminal to that host, and can list, read and update gists you have already created.
What is GitHub gist used for?
The README frames it as a place to upload code and other content from the terminal, with flags for private gists, descriptions, clipboard copying and opening the result in a browser.
How do I log in with the gist command?
Run gist --login. The default flow for github.com is a device-code OAuth flow that asks you to sign in at a URL and enter a code, after which the access token is stored in ~/.gist.
Why does gist say Bad credentials even though I created ~/.gist?
The README attributes this to line breaks in the token file. The file should contain only the token, optionally with a single trailing newline.
Can gist upload more than one file at a time?
Yes. The README shows gist a b c and gist *.rb for the command, and Gist.multi_gist with a hash of filenames to contents for the Ruby library.
How do I point gist at GitHub Enterprise instead of github.com?
Export GITHUB_URL with your Enterprise URL. The token is then stored in a host-specific file such as ~/.gist.http.github.internal.example.com. To return to public GitHub you must unset GITHUB_URL rather than set it to the public URL.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/defunkt-gist)Star history chart for your README
[](https://hysenlabs.com/projects/defunkt-gist)Was this useful?