snip-it (snp) is a fast, terminal-first snippet manager for commands and
short scripts. Save commands as plain TOML, find them with fuzzy search, fill in
variables at use time, and run, copy, inspect, or insert them from a
keyboard-driven TUI.
Inspired by pet and its simple, editable snippet format, snip-it adds libraries, richer TUI navigation, shell integration, themes, and optional self-hosted encrypted sync.
Commands chosen with
snp runare executed through your shell exactly as stored after variable expansion. Snip-it is a snippet manager, not a sandbox or secrets manager. Only save and run commands you trust.
curl -fsSL https://raw.githubusercontent.com/eggstack/snip-it/main/packaging/install.sh | bashWindows (inspect before running):
irm https://raw.githubusercontent.com/eggstack/snip-it/main/packaging/install.ps1 -OutFile .\install-snip-it.ps1
Get-Content .\install-snip-it.ps1
& .\install-snip-it.ps1 -Component SnpOr from crates.io (needs Rust 1.94+):
cargo install snip-itThe installer also takes --server for snip-sync and --both; see
packaging/README.md for pinned installs and the
verification/fallback contract.
Store a snippet.
snp new 'git push origin <branch=main>' --description 'Push a branch' --tags git,releaseCommand> git push origin <branch=main>
Snippet added
See what you have stored.
snp list-----
Push a branch: git push origin <branch=main>
Tags: git, release
Use it. All three open the same fuzzy-search TUI: run executes the
snippet through your shell, clip copies it to the clipboard, search
inspects it.
snp run
snp clip
snp searchVariables are prompted for at use time and come in three forms:
ssh <user>@<host> # prompt for both
git checkout <branch=main> # prompt, pre-filled default
kubectl config use-context <ctx=|_dev_||_prod_|> # pet-compatible choice
snp get retrieves a snippet deterministically without opening the TUI or
executing it. Use it when a script needs a command:
snp get --query 'push a branch' --field commandgit push origin <branch=main>
--json returns the whole record, including the expanded command and the
snippet's stable ID:
snp get --query 'push a branch' --json{
"schema": 1,
"id": "legacy-6e766362842b1bf257b5f65bc7e87fb4afcc6f11f8847f2a4ad1415a76d40155",
"description": "Push a branch",
"command": "git push origin <branch=main>",
"expanded": "git push origin main",
"tags": [
"git",
"release"
],
"library": "snippets",
"library_id": ""
}snp get exits 3 when nothing matches and 5 when a query matches more
than one snippet (default --resolution unique). For machine-readable listings
use snp list --json or snp list --csv. The full exit-code table is in
docs/EXIT_CODES.md.
Snippets live in libraries. A fresh install uses a single snippets library;
create more when you want to separate contexts.
snp library create work
snp library set-primary work
snp new 'kubectl get pods' --description 'Pods' --library work
snp list --library workWhere supported, --library all targets every library at once. all is a
reserved name and cannot be used as a library name. See
docs/LIBRARY_SCOPE.md.
snp shell init prints functions and widgets for bash, zsh, and fish. Inspect
the output before sourcing it. It installs no key bindings by default.
snp shell init bash # inspect the generated code
# After review, add this line to ~/.bashrc:
eval "$(snp shell init bash)"
snp doctor --check-shell bash| Feature | Command | Detail |
|---|---|---|
| Import from pet | snp import pet <file> --dry-run |
docs/PET_COMPATIBILITY.md |
| Self-hosted encrypted sync | snp register --server <url> then snp sync run |
snip-sync/README.md |
| Auto-sync after local edits | snp sync config --auto-sync on |
docs/USER_GUIDE.md |
| Coding agents (MCP) | snp mcp instructions claude |
docs/MCP.md |
| Delete a snippet without a TUI | snp delete --query 'push a branch' |
docs/USER_GUIDE.md |
| Themes | press e in the TUI, or edit themes.toml |
docs/USER_GUIDE.md |
| Diagnostics | snp doctor --library <name> |
docs/USER_GUIDE.md |
Sync encrypts snippet content (description, command, tags) with AES-256-GCM before sending it, and the server stores only ciphertext for that content. Sync metadata, including snippet IDs, timestamps, device ID, and deletion markers, travels in the clear. The server also sees your API key as a bearer token. See docs/THREAT_MODEL.md for the trust boundary.
Everything lives under ~/.config/snp/ (or $XDG_CONFIG_HOME/snp/). The
first write creates snippets.toml, logs/, and .transaction/; the rest
appear as you use the features.
| Path | Purpose |
|---|---|
snippets.toml |
Your snippets, as plain TOML. |
libraries/ |
Additional libraries, one TOML file each. |
libraries.toml |
Library index and which one is primary. |
sync.toml |
Sync server and account settings. |
logs/ |
Rotating debug logs. |
.transaction/ |
Crash-recovery journals. Do not edit. |
The API key for sync is kept in your OS keychain, not in sync.toml. See
docs/USER_GUIDE.md for the full set of
paths, environment variables, and auto-sync settings.
Start with the docs index.
| Document | Subject |
|---|---|
| docs/USER_GUIDE.md | Task-oriented guide: libraries, variables, pet import, shell integration, themes, sync, auto-sync, recovery |
| docs/COMMANDS.md | Command overview and common selection behavior |
| docs/EXIT_CODES.md | Stable exit codes 0–10 and their meaning |
| docs/COMMAND_CONTRACTS.md | Per-command behavior, startup recovery, stdout/stderr split |
| docs/LIBRARY_SCOPE.md | How --library resolves |
| docs/MCP.md | The read-only MCP server and its tools |
| docs/PET_COMPATIBILITY.md | Pet file compatibility and migration |
| docs/THREAT_MODEL.md | Sync trust boundary and what is not encrypted |
| docs/IDENTITY_CONTRACT.md | How snippet IDs are derived |
| SECURITY.md | Reporting a vulnerability and current posture |
Contributors and reviewers should start with architecture/overview.md, which includes the module map, cross-cutting invariants, and an index of 62 per-component deep dives.
MIT. See LICENSE.
