Command line snippets

The fine art of snippet curation

If you use the command line a lot, and have a built up a collection of complex one-liners or other snippets, you might want to curate your snippets.

I put this together for folks who enjoy using their Unix-like operating system command line, and for those who would also like to learn about a neat tool for curating a collection of command line snippets.

Consider the cognitive overload associated with recalling powerful, but seldom used commands. For example, you might want to extract the files from a Debian .deb formatted package on a BSD style system, but do you recall the command you used to do that 8 months ago?

ar vx <package_name.deb>

or how about showing the number of connections in use by PID for a process with strace?

strace -p $(pidof <process_name>) \
  -f \
  -e trace=network \
  -s 10000

How do I add an Internet password to the macOS Keychain from the command line again? Oh, yeah it's:

security -v add-internet-password \
  -a <account> \
  -s <server> \
  -w <password>

All the handy snippets a regular command line user can't fit in their mind need some other place to live. For many, this place can be a text file of some sort — so how about the idea of using a text file of a certain format that brings useful per-snippet attributes and works with neat CLI tools for managing and searching them?

Some people find success with the built-in snippet capabilities of their preferred text editor. Having never really tried my editor's own snippet system, I wanted a more universal tool where the snippets are managed right where they are used.

For a while, I used a GitHub gist to stash my snippets. Then eventually, a git repository of Markdown documents represented my carefully cataloged snippet collection. This solution became cumberson and not easy to search. Never mind the difficulty in synchronizing snippets between systems.

Say hello to pet

Now I use pet (opens in a new tab) by Teppei Fukuda (opens in a new tab) for snippet curation. pet is a fantastic and focused, Go based CLI tool that you use to manage a TOML formatted snippet file.

After using pet for about one year, I've found it a minimal, but powerful approach to curating all of my snippets.

The simplest first example to just list the snippets:

pet list

The output from this command shows the complete raw TOML of your snippet collection:

As your personal collection of snippets increases in number, you can use pet search to quickly find them:

pet search

pet can automatically interface with two popular interactive filtering and selector CLI tools, fzf (opens in a new tab) or peco (opens in a new tab) to make navigation and searching of your snippet collection a breeze.

You can also tag snippets with # and search for tagged snippets by tag.

You can pass the search result/composed command to a clipboard wrangling tool like pbcopy on macOS:

pet search | pbcopy

and have the command ready to use with a ⌘+v.

For Linux, you can do the same with xclip or xsel.

pet search | xclip -selection clipboard

You can also use dynamic argument placeholders for example values in snippets, and pet will prompt you for the actual values. pet can then insert the actual values into the composed command line.

In practice, the UI prompting appears as shown in the following screenshot, which contains 3 arguments: a filename, a source string value, and a replacement string value.

This results in a nicely composed and ready to use command line, like this:

find ./ -name test-file.txt \
  -exec sed -i '' -e 's/sashimi/nigiri/g' {} \;

You can use other pet commands to add new entries, like pet new or edit the existing snippets with pet edit, which will invoke the editor you specify in the configuration file.

You can also use pet sync to synchronize your snippet collection to a GitHub gist or to GitLab, and use them across environments.

pet sync
Upload success

Check out the pet README (opens in a new tab) for full documentation and usage examples!

hashipets

As an example of a fairly comprehensive snippet collection, I created hashipets (opens in a new tab), a curated collection of helpful snippets for HashiCorp command line tools like Vault (opens in a new tab), Consul (opens in a new tab), Nomad (opens in a new tab), Packer (opens in a new tab), Vagrant (opens in a new tab), and Terraform (opens in a new tab).

Based on the accompanying README (opens in a new tab) from the hashipets project, I'll show you how to use them with pet and peco on Linux.

Install pet

You can install pet on some Linux distributions with the package manager.

Visit https://github.com/knqyf263/pet/releases (opens in a new tab), and download the correct package file for your OS and distribution.

For example, you can download pet_0.8.4_linux_amd64.deb on an Ubuntu based distritbution:

wget https://github.com/knqyf263/pet/releases/download/v0.8.4/pet_0.8.4_linux_amd64.deb

Then install it:

sudo dpkg -i pet_0.8.4_linux_amd64.deb

Check the version to verify install:

pet version

Choose a fuzzy finder selector

You need to choose a fuzzy finder for use by pet to provide the convenience features, like searching. Common tools which pet supports for this include fzf (opens in a new tab) and peco (opens in a new tab).

The hashipets project example uses peco, so this guide will as well. Feel free to try fzf if you'd like an alternative.

Install peco

You can install peco from the apt package:

sudo apt update && sudo apt install -y peco

Check the version to verify install:

peco --version
peco version v0.5.10 (built with go1.17)

Time to onfigure pet and peco.

Configure pet to use hashipets snippets

In this example, you can clone the hashipets repository to a temporary directory, then configure pet to use its snippets.

export HASHIPETS=/tmp/hashipets
git clone https://github.com/brianshumate/hashipets.git "${HASHIPETS}"

Now configure pet:

pet configure

Use the value from $HASHIPETS to create the full path for the SnippetFile option value: /tmp/hashipets/hashipets.toml.

Change the SnippetFile option in the configuration so that these two are updated:

[General]
  SnippetFile = "/tmp/hashipets/hashipets.toml"
  SelectCmd = "peco --layout=bottom-up"

Some explanation of the config.toml example:

• General pet settings
  • SnippetFile: the path to our snippets
  • editor: the editor invoked with pet edit
  • column: the target display column width
  • selectcmd: the command line for the select/search tool
• Gist settings
  • file_name the gist filename
  • access_token: the GitHub personal access token
  • gist_id the gist ID string
  • public whether the gist is public or not

Configure peco

You can set up a custom peco configuration if you'd like as well; the one from hashipets makes for a good fun start:

mkdir -p ~/.config/peco &&
  tee ~/.config/peco/config.json <<EOF
{
    "Prompt": "🐶  pet>",
    "Style": {
        "Basic": ["on_default", "default"],
        "SavedSelection": ["bold", "on_yellow", "white"],
        "Selected": ["underline", "on_cyan", "black"],
        "Query": ["yellow", "bold"],
        "Matched": ["white", "bold"]
    }
}
EOF

You can now try a command to get started; go ahead and search the hashipets snippets:

pet search

Provided all went well, you should have a snippet list that you can search and filter:

I hope this article and the ideas in it are interesting or useful to you.

Enjoy!