Skip to content
/ gists.cli Public

Python based command line Gist management. Easy access to read and create Gists / snippets.

pypi.python.org/pypi/gists.cli

License

GPL-3.0 license
15 stars 6 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

khilnani/gists.cli

BranchesTags

Repository files navigation

Table of Contents generated with DocToc

Gists.cli

An easy to use CLI to manage your GitHub Gists. Create, edit, append, view, search and backup your Gists.

Overview

I'm a Developer who uses VI and the like. iPad and iPhone apps are great, but when I really need a Gist i'm at the command line.

The primary goal is to create something designed specifically to capture quick notes/links while requiring minimum typing. In addition to conventional view, download, edit and delete support, the application attempts to consider a variety scenarios -

  • Append - Ability to append text to a Gist instead of having to download, edit and update.
  • iOS support - Pythonista is pretty damn cool. Use Pypi.py or Pipista
  • VGA terminals - Using a mouse to copy/paste Gists IDs is great, but when a mouse is not handy index number can be used instead of a Gist IDs.
    • Use gists .1 or gists :1 or gists %1 to view the first Gist. Easier but less explicit than gists 233HSHS2233
  • Executing without download - You can pipe the output from the application to an interpreter as appropriate. eg. gists 1111 | sh
  • Each command/action has aliases/formats to suit your preferences.
    • Use gists --help or gists -h if you prefer standard CLI optiions, or just gists help or gists h if you want to type less

For the Casual User

Installation

  • Mac OS X / Linux
    • sudo easy_install gists.cli
  • Using PIP
    • Install Python Setup Tools
    • Install the Python package manager PIP (http://www.pip-installer.org/)
      • Run sudo easy_install pip
    • Once PIP is installed,
      • Run sudo pip install gists.cli
      • Run sudo pip install gists.cli --upgrade if upgrading.
      • Check the installed version by running pip show gists.cli

Authentication

Two factor authentication (SMS and Application) supported as of 0.350

  • By default the application will attempt to use Basic Auth to authenticate i.e. will prompt for username/password each time it is run.
  • If the file ~/.git-credentials is available, it will use the first OAuth token entry.
  • If the file ~/.gists with a Github OAuth token is found, it will be given preference over the above two mechanisms.
  • Run gists token|--token|t|-t to avoid the username/password prompt and to use an OAuth Token other than ~/.git-credentials. Saves to ~/.gists.

Usage

All the commands below are interactive and will prompt for user input (eg. public/private, descriptions) and confirmations (eg. directory creation).

Each Action/Command has multiple alias e.g. Create can be invoked not only by gists new|create, but also gists c|n|new|create|--new|--create|-n|-c Run gists help|--help|-h|h for more info.

List all your Gists

  • gists

View a Gist

  • gists ID - View all files within a Gist with ID on the console.

ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

Download a Gist

  • gists ID PATH - Download Gist files with ID to PATH. Will prompt for confirmation.

ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

Create a Gist

We'll prompt for stuff like Gist type (public/private), Description and Gist Content as needed.

  • gists new or gists create.
  • gists FILE - Create a Gist using the contents of FILE
  • gists "Content" - Create a Gist using the string "Content"

To avoid the Public/private Gist type prompt -

Bool should be true for Public, false for Private

  • gists Bool FILE
  • gists Bool "Content"

Append to a Gist

  • If Description or Content is '?', that field will be skipped.
    • eg. gists 223322 ? "New link to cool site" will append a new line but will not update the Description
    • eg. gists 223322 "Updated Description ? will only update the Description
  • ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

NOTE - If a Gist contains more than one file, each file will have a new line appended with the content sent.

  • gists ID Description FILE
  • gists ID Description "Content"

Delete to a Gist

  • gists delete ID - Will prompt for confirmation.

For The Advanced User

Tips

  • Each Action/Command has multiple alias e.g. Create can be invoked not only by gists new|create, but also gists c|n|new|create|--new|--create|-n|-c Run gists help|--help|-h|h for more info
  • ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N
  • Add debug|--debug to the end of any execution to view low level details. eg. gists debug. NOTE - This will reveal your OAuth ID but not your Basic Auth password.
  • Add supress|silent|--supress|--silient at the end of any execution to supress any prompts of confirmations if you like to live dangerously.
  • eg. gists -n FILE --supress --debug.

Usage

In addition to the usage examples above, you can also gain additional flexibility by specifying command line options (eg. -g, --get)

All the commands below are interactive and will prompt for user input.

List all your Gists

  • gists list|--list|-l|l

View a Gist

  • gists view|--view|v|-v ID - View all files within a Gist with ID on the console.
  • gists view|--view|v|-v ID FILE - View a specific file (FILE) in a Gist on the console. The matching is case-insensitive.

ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

Download a Gist

  • gists get|--get|g|-g ID PATH - Download Gist files with ID to PATH. Will prompt for confirmation.
  • gists get|--get|g|-g ID FILE PATH - Download a specific file (FILE) in a Gist to PATH. The matching is case-insensitive.

ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

Setup OAuth token

  • gists token|t|--token|-t - Setup to use OAuth Token other than ~/.git-credentials. Saves to ~/.gists.

Create a Gist

  • FILE - is a file path, relative or absolute.
  • Bool - True for Public, False for Private. Supports True, False, 1, 0, Yes, No, y, n. Case-insensitive
  • Description and Content - Text content within quotes

Without specifying a command (eg. create, new), the application will trying to figure it out. However, this supports fewer combinations of arguments.

  • gists FILE
  • gists "Content"
  • gists Bool FILE
  • gists Bool "Content"
  • gists "Description" FILE
  • gists "Description" "Content"
  • gists Bool "Description" FILE
  • gists Bool "Description" "Content"

If you like to type, or be specific you can also use the command line option. You will be prompted for stuff like Gist type, Description and Gist Content etc as needed.

OPTION = new|--new|n|-n|create|--create|c|-c

  • gists OPTION
  • gists OPTION FILE
  • gists OPTION "Content"
  • gists OPTION Bool FILE
  • gists OPTION Bool "Content"
  • gists OPTION "Description" FILE
  • gists OPTION "Description" "Content"
  • gists OPTION Bool "Description" FILE
  • gists OPTION Bool "Description" "Content"

Append to a Gist

  • If Description or Content is '?', that field will be skipped.
    • eg. gists 223322 ? "New link to cool site" will append a new line but will not update the Description
    • eg. gists 223322 "Updated Description ? will only update the Description
  • ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

Without specifiying a specific action, the following will result in an Append.

NOTE - If a Gist contains more than one file, each file will have a new line appended with the content sent.

  • gists ID Description FILE
  • gists ID Description "Content"

For more control/specificity

OPTION = append|--append|a|-a

  • gists OPTION ID File
  • gists OPTION ID Content
  • gists OPTION ID Description File
  • gists OPTION ID Description Content

Update

  • If Description or Content is '?', that field will be skipped.
    • eg. gists 223322 ? "New link to cool site" will append a new line but will not update the Description
    • eg. gists 223322 "Updated Description ? will only update the Description
  • ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

NOTE - A file in a Gist will be updated only if the file name sent is an exact match. If not file name match is found, a new file is added to the Gist.

OPTION = update|--update|u|-u

  • gists OPTION ID File
  • gists OPTION ID Content
  • gists OPTION ID Description File
  • gists OPTION ID Description Content

Delete

  • gists delete|del|d|--delete|--del|-d ID - Delete a Gist. Will prompt for confirmation.

ID can be a Gist ID or Index ID (of the Gist in the List view) Index must be in the format '#N', %N , .N or :N

In Development

Export/Backup

  • gists backup|b|--backup|-b [DIR] - Backup all Gists in the user's account.

Search

  • gists search|query|q|--search|--query|-q QUERY - Search Gists.

Misc

  • gists stars|--stars - List starred Gists

For the Developer

Installation

If you would like to contribute changes to the code base

  • Get the code
    • Fork and git clone the fork, or ...
    • git clone https://github.com/khilnani/gists.cli.git, or ...
    • Download the latest Tag Archive from https://github.com/khilnani/gists.cli
      • Downloading the Archive is not recommended, since it won't be easy to merge code back.
  • Install dependencies by running ./dependencies.sh.
    • This installs PIP (if not already installed) and then installs the dependencies.
  • Run the installer as below. If you get any error run with sudo ...
    • ./install.py with no arguments will install to /usr/local/bin.
    • ./install.py INSTALL_PATH will install to a specific directory.

Non-Mac/OS X System Testing

Issues and Roadmap

Troubleshooting

  • If you get the error Wheel installs require setuptools >= 0.8 for dist-info support or ImportError: No module named pkg_resources, please ensure you have upgraded setup tools. See the 'Install Python Setup Tools/Manual Install' section above to upgrade setup tools.
  • If you get the error AttributeError: VerifiedHTTPSConnection instance has no attribute '_tunnel_host, this is likely due to you running Python 2.6.2 or earlier.
    • Running sudo pip install requests==1.2.3 resolves the issue. The requests 2.0 library uses urllib3 that uses some capabilities only available in Python 2.6.3

Credits

About

Python based command line Gist management. Easy access to read and create Gists / snippets.

pypi.python.org/pypi/gists.cli

Topics

python cli gists gists-files

Resources

Readme

License

GPL-3.0 license
Activity

Stars

15 stars

Watchers

1 watching

Forks

6 forks
Report repository

Releases

9 tags

Packages

No packages published

Contributors 2

  •  
  •  

Languages