snippet

Parameterized command templates for your terminal.

Save commands once, reuse them forever — with placeholders, defaults, fuzzy search, and composable output.

Usage

$ snippet -e archive/extract-tgz -f 'tar -xzvf <archive>'
$ snippet -t archive/extract-tgz /path/to/foo.tar.gz
tar -xzvf /path/to/foo.tar.gz

Why

Shell aliases are static. History search is fragile. Neither lets you say "run this shape of command, but with these arguments this time."

snippet sits in between: it stores command templates with named placeholders, and fills them on demand. Think of it as printf for your shell history.

Install

pip3 install snippet-cli

Optional — enable tab completion for template names:

eval "$(register-python-argcomplete snippet)"

Quick start

Save a command you'll reuse

# Save or edit a snippet (opens $EDITOR)
$ snippet -e archive/create-tgz -f "tar -czvf <archive> <file...>"

Recall it later

# Exact match
$ snippet -t archive/create-tgz backup.tar.gz file=src/ README.md
tar -czvf backup.tar.gz src/ README.md

# Fuzzy search (opens fzf when no exact match)
$ snippet -t archive

Run it directly

$ snippet -t archive/create-tgz backup.tar.gz file=src/ README.md | bash

Key Features

Permutations and Repeatables

When you pass multiple values to regular placeholders, snippet generates every combination:

$ snippet -f "kubectl cp <file> <namespace>/<pod>:/tmp/<file>" namespace=default pod=example-pod file=busybox nmap tcpdump
kubectl cp busybox default/example-pod:/tmp/busybox
kubectl cp nmap default/example-pod:/tmp/nmap
kubectl cp tcpdump default/example-pod:/tmp/tcpdump

When you add three dots at the end of a placeholder (e.g., <file...>), values are concatenated instead of permuted:

$ snippet -f "tar -czvf <archive> <file...>" backup.tar.gz file=src/ README.md
tar -czvf backup.tar.gz src/ README.md

By default arguments which are associated with a repeatable placeholder are separated by space. To specify a custom character sequence you may use the join codec:

$ snippet -f "nmap -sS -p<port...|join:','> <rhost...>" port=80 443 rhost=192.168.0.1 192.168.0.2
nmap -sS -p80,443 192.168.0.1 192.168.0.2

Default and Optionals

# Default value — used when nothing is provided
$ snippet -f "python3 -m http.server <lport='8000'>"
python3 -m http.server 8000

# Optional section — disappears entirely if placeholder is empty
$ snippet -f "python3 -m http.server[ --bind <lhost>][ <lport>]" lport=4444
python3 -m http.server 4444

If you need square-brackets to be part of the string format you need to escape them accordingly:

$ snippet -f "\[<arg>\]" hello
[hello]

Codecs

Transform placeholder values with piped codecs. Useful when your archive paths contain spaces:

$ snippet -f "tar -czvf <archive|squote> <file...|squote>" backup.tar.gz file="my docs/" notes.md
tar -czvf 'backup.tar.gz' 'my docs/' 'notes.md'

Codecs can be parameterized and are chainable:

$ snippet -f "cp <file|squote> <file|add:'.bak'|squote>" "/path/to/my file"
cp '/path/to/my file' '/path/to/my file.bak'

Run snippet --list-codecs to see all available transforms.

Presets

Built-in dynamic placeholders like <datetime> — handy for timestamped archives:

$ snippet -f "tar -czvf '<datetime>.tar.gz' <file...>" file=src/
tar -czvf '20250302143012.tar.gz' src/

Customize presets in ~/.snippet/snippet_profile.py.

Input from env vars, files, or pipes

# Export variables to a sourceable env file
$ snippet --env -f "tar -czvf <archive> <file...>" archive=backup.tar.gz file=src/ README.md | tee env.sh
export archive="backup.tar.gz"
export file="\('src/' 'README.md'\)"

# Import environment variables from file
$ source env.sh && snippet -f "tar -czvf <archive> <file...>"

# Load variable values from a file
$ snippet -f "tar -czvf <archive> <file...>" backup.tar.gz file:filelist.txt

# Load format string from a pipe
$ echo "tar -czvf <archive> <file...>" | snippet backup.tar.gz file=src/

Organizing templates

Templates live in ~/.snippet/templates/ and support directory-style namespacing:

$ snippet -e archive/create-tgz -f "tar -czvf <archive> <file...>"
$ snippet -e archive/extract-tgz -f "tar -xzvf <archive>"
$ snippet -e net/scan -f "nmap -sS -p <port> <host>"

$ snippet --list-templates
archive/create-tgz
archive/extract-tgz
net/scan

Organizing codecs

Custom codecs can be added into ~/.snippet/codecs/. Here's a minimal example:

import os.path

from snippet.codecs import StringCodec


class Codec(StringCodec):
    """ Extracts the filename from a file path. """

    def __init__(self):
        super().__init__(author="bytebutcher", dependencies=[])

    def run(self, input):
        return os.path.basename(input.encode('utf-8', errors="surrogateescape")).decode('utf-8', errors="surrogateescape")

Advanced usage

snippet supports multi-line format strings:

$ cat input.txt
{
   "foo": "<foo>",
   "bar": "<bar>"
}
$ cat input.txt | snippet egg spam
{
   "foo": "egg",
   "bar": "spam"
}

snippet can be used to easily execute alternating commands in sequence:

$ snippet -f "echo 'hello <arg1>';" arg1=snippet world | bash
hello world
hello snippet

Using xargs the resulting commands can also be executed in parallel:

snippet -f "echo 'hello <arg1>';" arg1=snippet arg1=world | xargs --max-procs=4 -I CMD bash -c CMD
hello world
hello snippet

How it compares

See also

To make the most out of this tool you might also consider to look into the following projects:

• snex - previews and optionally executes snippets
• mkenv - creates and updates shell environment files