Skip to content
Gist command line interface
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests tests: added test_list_empty May 7, 2018
.gitignore gist: added venv/ to .gitignore Mar 20, 2019
.travis.yml tox: update python versions to test Mar 31, 2019
LICENSE Initial commit Feb 16, 2015 setup: added share/gist.zsh to Apr 4, 2015
README.rst Merge pull request #48 from tctony/master Feb 19, 2018
requirements.txt specify minimum python-gnupg version Nov 4, 2017



'gist' is a command line interface for working with github gists. It provides several methods for inspecting a users gists, and the ability to easily create them.


To install 'gist' you can either use,

$ sudo pip install python-gist


$ sudo python install


$ sudo make install

This will install the python package 'gist' to the standard location for your system and copy the license, readme, and some shell scripts into /usr/share/gist.

There are also script to provide tab-completion for bash, fish, and zsh shells. The scripts are installed in /usr/local/share/gist.

There are 3 different scripts for tab-completion in bash: gist.bash, gist-fzf.bash, and gist-fzsl.bash. The first, provides simple tab completion and can be enable by adding the following to your .bashrc file,

source /usr/local/share/gist/gist.bash

The other scripts, gist-fzf.bash and fist-fzsl.bash, provide fuzzy matching of gists using an ncurses interface (NB: these scripts require fzf and fzsl, respectively, to be installed -- see Dependencies).

The script provides tab completion for the fish shell, and should be copied to ~/.config/fish/completions.

The gist.zsh script provides tab completion for the zsh shell, and should be copied to ~/.zsh as _gist. If not already in your ~/.zshrc file, you should add

fpath=(${HOME}/.zsh $fpath)

To check that 'gist' is operating correctly, you can run the unit tests with,

$ python test

Getting started

'gist' requires a personal access token for authentication. To create a token, go to The token needs to then be added to a 'gist' configuration file that should have the form,

token: <enter token here>
editor: <path to editor>

The editor field is optional. If the default editor is specified through some other mechanism 'gist' will try to infer it. Otherwise, you can use the config file to ensure that 'gist' uses the editor you want it to use.

The configuration file must be in one of the following,


If more than one of these files exist, this is also the order of preference, i.e. a configuration that is found in the ${XDG_DATA_HOME} directory will be taken in preference to ${HOME}/.config/gist.

Also, 'gist' assumes that you have set up your github account to use SSH keys so that you can access your repositories without needing to provide a password. Here is a link on setting up SSH keys with github.


'gist' is intended to make it easy to manage and use github gists from the command line. There are several commands available:

gist create      - creates a new gist
gist edit        - edit the files in your gist
gist description - updates the description of your gist
gist list        - prints a list of your gists
gist clone       - clones a gist
gist delete      - deletes a gist or list of gists from github
gist files       - prints a list of the files in a gist
gist archive     - downloads a gist and creates a tarball
gist content     - prints the content of the gist to stdout
gist info        - prints detailed information about a gist
gist version     - prints the current version

gist create

Most of the 'gist' commands are pretty simple and limited in what they can do. 'gist create' is a little different and offers more flexibility in how the user can create the gist.

If you have a set of existing files that you want to turn into a gist,

$ gist create "divide et impera" foo.txt bar.txt

where the quoted string is the description of the gist. Or, you may find it useful to create a gist from content on your clipboard (say, using xclip),

$ xclip -o | gist create "ipsa scientia potestas est"

Another option is to pipe the input into 'gist create' and have it automatically put the content on github,

$ echo $(cat) | gist create "credo quia absurdum est"

Finally, you can just call,

$ gist create "a posse ad esse"

which will launch your default editor (defined by the EDITOR environment variable).

In addition to creating gists using the above methods, it is also possible to encrypt a gist if you have gnupg installed. Any of the above methods can be used to create encrypted gists by simply adding the --encrypt flag to invocation. For example,

$ gist create "arcana imperii" --encrypt

will open the editor allowing you to create the content of the gist, which is then encrypted and added to github. See the Configuration section for information on how to enable gnupg support.

gist edit

You can edit your gists directly with the 'edit' command. This command will clone the gist to a temporary directory and open up the default editor (defined by the EDITOR environment variable) to edit the files in the gist. When the editor is exited the user is prompted to commit the changes, which are then pushed back to the remote.

gist description

You can update the description of your gist with the 'description' command. You need to supply the gist ID and the new description. For example -

$ gist description e1f5e95a1705cbfde144 "This is a new description"

gist list

Returns a list of your gists. The gists are returned as,

2b1823252e8433ef8682 - mathematical divagations
a485ee9ddf6828d697be - notes on defenestration
589071c7a02b1823252e + abecedarian pericombobulations

The first column is the gists unique identifier; The second column indicates whether the gist is public ('+') or private ('-'); The third column is the description in the gist, which may be empty.

gist clone

Clones a gist to the current directory. This command will clone any gist based on its unique identifier (i.e. not just the users) to the current directory.

gist delete

Deletes the specified gists from github.

gist files

Returns a list of the files in the specified gist.

gist archive

Downloads the specified gist to a temporary directory and adds it to a tarball, which is then moved to the current directory.

gist content

Writes the content of each file in the specified gist to the terminal, e.g.

$ gist content c971fca7997aed65ddc9
this is foo

this is bar

For each file in the gist the first line is the name of the file followed by a colon, and then the content of that file is written to the terminal.

If a filename is given, only the content of the specified filename will be printed.

$ gist content de42344a4ecb6250d6cea00d9da6d83a file1
content of file 1

If the contents of the gist is encrypted, it can be viewed in its decrypted form by adding the --decrypt flag, e.g.

$ gist content --decrypt 8fe557fb3771aa74edfd
foo.txt.asc (decrypted):
this is a secret

See the Configuration section for information on how to enable gnupg support.

gist info

This command provides a complete dump of the information about the gist as a JSON object. It is mostly useful for debugging.

gist version

Simply prints the current version.


There are several parameters that can be added to a configuration file to determine the behavior of gist. The configuration file itself is expected to be one of the following paths,


The configuration file follows the .ini style. The following is an example,

token: dde7b84d1e0edf7454ab354934b6ab36b01bf00f
editor: /usr/bin/vim
gnupg-homedir: /home/user/.gnupg
gnupg-fingerprint: 179F9650D9FC1BFE391620B4B13A7829D8DE8623

The only essential field in the configuration file is the token. This is the authentication token from github that grants gist permission to access your gists. The editor is the editor to use if the EDITOR environment is not set or you wish to use a different editor. 'gnupg-homedir' is the directory where your gnupg data are stored, and 'gnupg-fingerprint' is the fingerprint of the key to use to encrypt data in your gists. Both gnupg fields are required to support encryption/decryption.


'gist' currently depends on,

  • docopts
  • >=python-gnupg-0.4.1
  • requests
  • simplejson

The following packages are required for testing,

  • responses
  • tox
  • pep8

Optional packages (for fuzzy matching)


Thank you to the following people for contributing to 'gist'!

You can’t perform that action at this time.