snip-it

snip-it (snp) is a terminal-first snippet manager for short scripts and commands. Save them in libraries, find them with fuzzy search, fill in variables when you use them, then run or copy them from a keyboard-driven TUI.

It was inspired by pet and keeps the same simple, editable TOML approach to command snippets. The optional snip-sync server adds encrypted synchronization for environments where you want one snippet collection available on multiple machines.

What snip-it provides

• Short command and script snippets stored as editable TOML.
• Separate libraries for work, home, projects, or environments.
• Fuzzy search, tags, syntax highlighting, clipboard support, and a TUI.
• Runtime variables such as <host> and <branch=main>.
• 50 bundled Halloy-compatible themes, plus support for dropping in additional Halloy theme files.
• Optional self-hosted sync using AES-256-GCM encryption and Argon2id key derivation. The server stores encrypted snippet payloads, not their descriptions or commands.
• Premade libraries served by snip-sync.

Commands are executed through your shell exactly as written. snip-it is a snippet manager, not a sandbox or a secrets manager; only save and run commands you trust.

Installation

Homebrew (macOS)

brew install eggstack/tap/snip-it

This installs the snp client with shell completions for Bash, Zsh, and Fish. The optional snip-sync server is not included. To upgrade:

brew upgrade snip-it

To uninstall:

brew uninstall snip-it

User configuration and snippet data are preserved by Homebrew unless manually removed.

From crates.io

cargo install snip-it

Rust 1.94 or newer is required when building from source.

Pre-built binaries

Download the binary for your platform from the latest GitHub release. Release assets currently include:

On Linux or macOS, extract the archive and install the binary:

tar xzf snp-*.tar.gz
sudo mv snp /usr/local/bin/snp

On Windows, extract the zip and move snp.exe to a directory on your PATH.

Each release also includes a SHA256SUMS file for verifying download integrity.

After installing the client, snp update checks the appropriate source and updates in place: crates.io for Cargo installs, Homebrew for Homebrew installs, and the matching GitHub release archive for standalone binaries. Use snp update --dry-run to check without installing.

From source

git clone https://github.com/eggstack/snip-it.git
cd snip-it
cargo build --release
mkdir -p ~/.local/bin
install target/release/snp ~/.local/bin/snp

The Docker image is for the optional sync server, not the interactive client:

docker pull ghcr.io/eggstack/snip-it/snip-sync:latest

Quickstart

Create a snippet, search it, and run or copy it:

snp new 'git push origin <branch=main>' --tags
snp list
snp run
snp clip
snp search

snp new prompts for a description (or accepts --description), and --tags also prompts for tags. Variable values are requested when a snippet is run or copied. In the TUI, press d in normal mode and confirm with y to delete the selected snippet; any other key cancels.

Snippet files

Without libraries, snip-it uses the legacy single-file layout:

$XDG_CONFIG_HOME/snp/snippets.toml

When XDG_CONFIG_HOME is unset, this is ~/.config/snp/snippets.toml.

Creating a library switches the installation to library mode. Existing snippets.toml content is migrated to libraries/snippets.toml when needed.

snp library create work
snp library set-primary work
snp new --library work 'kubectl get pods -n <namespace=default>'
snp run --library work

The canonical file format is compatible with pet's snippet format:

[[snippets]]
description = "Git commit with a message"
command = "git commit -m \"<message>\""
tag = ["git", "version-control"]
output = ""

The loader also accepts snip-it's older [[Snippets]] spelling and legacy capitalized field names. Snip-it-only metadata such as IDs, folders, favorites, and sync timestamps is preserved when snip-it writes a library. See USER_GUIDE.md for library layout, import/export, and the full configuration reference.

Themes

Snip-it reads the same color-theme TOML files used by Halloy. A Halloy theme file can be copied directly into:

$XDG_CONFIG_HOME/snp/themes/<name>.toml

When XDG_CONFIG_HOME is unset, use ~/.config/snp/themes/<name>.toml.

Then press e in the normal TUI mode to open the theme picker, preview themes, and press Enter to save the selection. The active theme is recorded in the config root's themes.toml. The SNP_THEME environment variable remains available for compatibility with the older dark, bright, light, and auto values, or a theme filename.

Snip-it uses Halloy's color schema and projects it onto the colors needed by the TUI. font_style and Halloy-specific UI colors that have no snip-it equivalent are ignored. Copy the theme file itself, not Halloy's main config entry such as theme = "...". See the Halloy theme guide and Halloy's theme repository.

Sync across environments

Sync is optional. It uses a self-hosted snip-sync server backed by SQLite. The client encrypts snippet descriptions, commands, and tags before sending them; the server handles authentication, library metadata, and ciphertext storage. The server does not terminate TLS, so a remote deployment must put it behind a TLS-terminating reverse proxy.

The complete deployment guide, including Docker, Caddy, systemd, configuration, health checks, and troubleshooting, is in snip-sync/README.md.

Local test server

cargo install snip-it snip-sync

# In one terminal:
snip-sync init --skip-cert
SNIP_SYNC_ALLOW_HTTP=true snip-sync serve

# In another terminal:
snp register --server http://127.0.0.1:50051
snp sync --push-only

Plaintext HTTP is for loopback development only. Do not expose this server directly to the internet.

Remote server and multiple environments

For a remote server, use an HTTPS URL terminated by your reverse proxy:

snp register --server https://sync.example.com

The sync server's current credential model is API-key based. snp register creates a new account and API key, so run it once for the collection you want to share. Every environment that should see that collection must be configured with the same server URL and API key; registering independently creates a separate account and separate libraries. Provision the key through your OS keychain or a secret manager, and never commit it to a repository or put it in shell history. The multi-environment section of USER_GUIDE.md shows the settings involved.

After the first environment has pushed its libraries, use bidirectional sync on each environment so local and remote changes are merged:

snp sync --push-only       # first environment: seed the server
snp sync --pull-only       # another environment: fetch the existing libraries
snp sync                    # after setting sync_direction = "Bidirectional"

Sync uses last-write-wins timestamps for shared fields. Keep the SQLite database on persistent storage and back it up along with the rest of the server data.

CLI overview

snp new          Create a snippet
snp list         List snippets
snp run          Run a snippet from the TUI
snp clip         Copy a snippet from the TUI
snp search       Search and inspect snippets
snp edit         Edit a snippet library in $EDITOR
snp library      Create, list, select, or delete libraries
snp premade      Browse and download premade libraries
snp register     Register with a snip-sync server
snp sync         Push, pull, or bidirectionally sync libraries
snp cron         Print a periodic sync schedule
snp keybindings  Show TUI keybindings
snp update       Check for and install an update
snp completions  Generate shell completions

Run snp <command> --help for command-specific options.

Configuration and security

The client configuration root is $XDG_CONFIG_HOME/snp when XDG_CONFIG_HOME is set, otherwise ~/.config/snp. Important files include:

API keys are stored in the operating system keychain when available. Set SNP_ALLOW_PLAINTEXT_API_KEY=true only for a deliberately controlled headless environment where keychain storage is unavailable. This stores the key in sync.toml and should be protected with restrictive file permissions.

Sync payloads use AES-256-GCM with an Argon2id-derived key. CRC32 integrity headers on local sync settings detect accidental partial writes but are not an anti-tampering mechanism. See SECURITY.md for the threat model and disclosure policy.

Common environment variables:

Documentation

• USER_GUIDE.md — libraries, pet compatibility, themes, sync, multi-environment provisioning, variables, premade libraries, and recovery.
• snip-sync/README.md — self-hosting and deploying the optional sync server.
• SECURITY.md — threat model and vulnerability disclosure.
• CONTRIBUTING.md — development and release workflow.
• CHANGELOG.md — release history.

License

MIT © 2026 David Bowman