snip
snip is a snippet manager that keeps its library in plain files. Code, notes,
and metadata are ordinary text you can grep, diff, edit in any editor, and put
under Git. It ships as a CLI and a terminal browser.
It grew out of wanting SnippetsLab's library available while coding with an AI agent. SnippetsLab stores everything in a database only that app can read, so nothing else — a script, an editor, an agent — can reach it. Files remove that limitation: every command speaks JSON, snippets are addressed by UUID, and writes are guarded by a content fingerprint so two writers can share one library without clobbering each other.
Runs on Linux, macOS, and Windows.
- Install · Quick start · What it does
- Terminal browser · Agent-friendly operations
- AI agent skills · Configuration
- Files are the database · Preview and editing
- SnippetsLab migration · Git backup and deletion
- Manual pages · Shell completion
- Development · License
Install
The crate is sniplab; the binary it installs is snip.
macOS / Linux (Homebrew)
Cargo
Prebuilt binary via cargo-binstall, no compilation:
Or build from crates.io (Rust 1.89 or newer):
Debian / Ubuntu
For Ubuntu 24.04+, Debian 13+, and derivatives (Mint 22, Pop!_OS 24.04, elementary OS 8, Zorin OS 17):
On arm64, swap x86_64 for aarch64.
Fedora / Enterprise Linux
For Fedora 40+ and the Enterprise Linux 10 family — RHEL 10.0+, Rocky Linux 10.0+, AlmaLinux 10.0+, Oracle Linux 10+, CentOS Stream 10+ — all of which ship glibc 2.39 or newer:
On arm64, swap x86_64 for aarch64.
Arch Linux
From the AUR. Builds from release source rather than repackaging the Ubuntu-built binary:
paru -S sniplab works too, or clone https://aur.archlinux.org/sniplab.git
and run makepkg -si.
Nix
Needs the nix-command and flakes experimental features. Linux and Apple
silicon; nixpkgs no longer supports Intel macOS.
The first run asks whether to trust the project's Cachix substituter; accept it to download a prebuilt binary instead of compiling on your machine.
Append a tag to pin a release: github:gitkeniwo/snip/vX.Y.Z. Or run it without
installing:
On NixOS, install it declaratively instead — add the flake input, then apply the overlay in a module:
inputs.snip = {
url = "github:gitkeniwo/snip";
inputs.nixpkgs.follows = "nixpkgs";
};
nixpkgs.overlays = [ inputs.snip.overlays.default ];
environment.systemPackages = [ pkgs.sniplab ];
Manual pages and shell completions ship with the package, so man snip works
without snip man install.
Windows (Scoop)
scoop update snip picks up new releases. x86_64 only for now.
Manual download
Binaries and packages are on the latest release:
| Platform | Asset |
|---|---|
| macOS (Apple Silicon) | snip-aarch64-apple-darwin.tar.gz |
| macOS (Intel) | snip-x86_64-apple-darwin.tar.gz |
| Linux x86_64 | snip-x86_64-unknown-linux-gnu.tar.gz, .deb, .rpm |
| Linux arm64 | snip-aarch64-unknown-linux-gnu.tar.gz, .deb, .rpm |
| Windows x86_64 | snip-x86_64-pc-windows-msvc.zip |
|
The Unix archives also carry man/; see Manual pages.
From source
For a smaller binary without the terminal browser, add --no-default-features.
Notes
Linux binaries are built on Ubuntu 24.04, so they need glibc 2.39 or newer.
Older systems — RHEL/Rocky/AlmaLinux/Oracle/CentOS Stream 9 and older
(glibc 2.34), Amazon Linux 2023 (2.34), Amazon Linux 2 (2.26), Ubuntu 22.04
(2.35), Debian 12 (2.36), openSUSE Leap 15 (2.31) — fall short; install with
cargo install sniplab there. Upgrading a .deb/.rpm means downloading the newer
file again.
Release history is in CHANGELOG.md.
Quick start
Install snip, then run it in an interactive terminal and answer the three
setup questions. It creates (or connects) a library and can make it your
default:
For scripts and remote shells, use the non-interactive path instead:
|
Then open the terminal browser:
When --library is omitted, SNIP_LIBRARY is checked next, then the nearest
snip.toml walking up from the current directory, and finally default_library
in the user config. Commands run inside a library never jump to the global
default.
What it does
- Plain-file library. One directory per snippet, holding fragments, notes, a README, and a TOML manifest. FORMAT.md specifies it normatively.
- CLI for everything. Create, list, search, show, edit, move, tag, trash,
restore, import, and repair, with
--output jsonorjsonlon every command. - Terminal browser. Three-pane TUI with syntax highlighting, live reload, and mouse support.
- Concurrency-safe writes. Library lock, atomic writes, and
--if-hashfingerprint checks so a writer cannot overwrite a version it never read. - Structure-aware search. Regex, field filters, and context lines, so it
replaces
grep/rgover the library. - SnippetsLab import. Preserves UUIDs, hierarchy, tags, flags, timestamps, content, and notes.
- Optional Git backup. Commit, push, and fetch scoped to the library, with an interactive console in the TUI.
- Agent skill.
skills/snippackages the CLI contract for coding agents.
Terminal browser
Three panes: folders and tags on the left, snippets in the middle, a preview on the right. Selecting a folder or tag filters the list. A file watcher picks up changes made outside the browser.
| Key | |
|---|---|
? |
the full key map |
: / Ctrl-P |
command palette |
/ |
search |
Tab, h/l |
switch pane; back out or drill in |
j/k, g/G |
move; first/last |
n, e, d |
create, edit in $EDITOR, move to trash |
y |
copy content |
Ctrl-g |
Git console |
Keys are named after the CLI commands they run, so r on a folder is snip folder rename. The mouse works as expected: click to focus, double-click to
drill in, scroll the pane under the cursor, drag across the preview to copy.
Command palette
: or Ctrl-P opens a fuzzy-matched list of every command, each spelled out
(Folder: Rename, Snippet: Rename, Git: Commit) and runnable regardless of
which pane has focus. Commands that cannot run right now stay visible, greyed
out with the reason; the rest show their key binding, so the palette doubles as
a way to learn the shortcuts.
Appearance
On macOS the TUI follows the system light/dark setting and updates while it
runs; Linux uses GTK_THEME or COLORFGBG when available. Override it for a
terminal whose background differs from the system:
SNIP_TUI_THEME=light
Any other SNIP_TUI_THEME value selects a theme by name for that run — see
Themes.
Themes
Open the command palette and run Change Color Theme to preview every theme
for the current light or dark appearance; Esc restores the previous theme and
Enter saves the choice. The same slots can be set from the command line:
snip theme use saves to the theme's own slot unless --appearance light|dark
forces another. Theme names go in the tui-light-theme/tui-dark-theme slots
(see Configuration); tui-theme only picks auto|light|dark.
User themes live in the directory printed by snip theme path (normally
~/.config/snip/themes). See docs/themes.md for the complete
format, inheritance, validation, and base16 role mapping.
Language badges are plain ASCII ([rs], [py], [sh], [md]) so they render
in any font. The rounded caps on the top and bottom bars are Powerline glyphs,
which need a Nerd Font or another Powerline-patched terminal font.
Agent-friendly operations
Every command takes --output json or jsonl. Use UUIDs from that output for
deterministic operations; titles are accepted only when they identify exactly one
snippet.
# Search is structure-aware, so it replaces grep/rg over the library
# Content, notes, and READMEs take an inline value or a file (- is stdin)
search results carry the snippet's fingerprint, so a metadata change can go
straight to --if-hash without a separate show. Commands that would open an
editor fail with a usage error when stdout is not a terminal, so scripts never
block on an editor that cannot appear.
Structured stdout is kept separate from errors. Exit codes are stable:
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | I/O or internal failure |
| 2 | invalid CLI usage |
| 3 | missing or ambiguous selector |
| 4 | lock or fingerprint conflict |
| 5 | invalid library data |
AI agent skills
skills/snip packages all of the above into a skill any
agent can load: vocabulary, selectors, JSON payload shapes, and the --if-hash
workflow. Symlinking keeps it current as the CLI evolves.
&&
~/.agents/skills/ is the vendor-neutral location. Support for it is still
uneven, so also link it into the directory your agent actually reads:
~/.claude/skills/ (Claude Code), ~/.codex/skills/ (Codex),
~/.opencode/skills/ (opencode), ~/.omp/skills/ (oh-my-pi). One pass covers
whichever of them exist:
for; do
[ || continue
done
Or hand the job to the agent itself:
Install the snip agent skill from
https://github.com/gitkeniwo/snip/tree/main/skills/snip
Fetch that directory (SKILL.md plus everything under references/) and put it at
~/.agents/skills/snip if you read that location, otherwise your own skills
directory. If the snip repository is already cloned locally, symlink its
skills/snip instead of copying, so the skill tracks the CLI. Then tell me the
path you used and confirm `snip --version` runs.
Once loaded, the agent works the library directly:
Save the fish function we just wrote to snip under Shell/Fish, tag it fish and
clipboard, and add a note explaining why the pbcopy fallback is there.
My fish config drifted from the copy in snip. Diff ~/.config/fish/config.fish
against that snippet and update whichever is stale, keeping the note intact.
Run brew bundle dump, compare it with the Brewfile snippet in snip, and commit
the update to the library's Git repo if anything changed.
The skill assumes snip is on PATH and a library is reachable. See
skills/README.md for project-scoped installs, the Claude
Agent SDK, and runtimes that take a system prompt instead of skill files.
Configuration
The config lives at $XDG_CONFIG_HOME/snip/config.toml, or
~/.config/snip/config.toml when XDG_CONFIG_HOME is unset.
Supported values can be changed without editing TOML by hand:
The complete schema is:
= 1
= "/path/to/Main.sniplib"
= "human" # human | json | jsonl
= "auto" # auto | always | never
= "ansi" # ansi | plain | html
= false
= "nvim -f"
= "less -R"
= "text"
= ""
= ["personal"]
[]
= "auto" # auto | light | dark
= "light-default"
= "dark-default"
= "modified" # modified | created | title
= "comfortable" # comfortable | compact
= true # preview gutter; toggled with `N`
[]
= 0 # minutes; 0 disables automatic Git operations
= false # push ahead commits in the background
= false
SNIP_TUI_THEME=light|dark overrides [tui].theme; any other non-empty value
selects a theme by name for that run. Config values are defaults
only; explicit CLI options override them. Unknown TOML fields are preserved when
snip config set or unset rewrites the file, so future settings can coexist.
Files are the database
Main.sniplib/
├── snip.toml
├── tags.toml
├── snippets/
│ └── Dotfiles/
│ └── Brewfile--a5792745/
│ ├── snippet.toml
│ ├── README.md
│ ├── fragments/001-Brewfile
│ ├── notes/001.md
│ └── attachments/
├── trash/
├── .snip/
└── .gitignore
The path below snippets/ is the folder hierarchy, and a directory is a
snippet if it contains snippet.toml. Directory names are descriptive only, so
you can move or rename them by hand; the UUID in the manifest is the stable
identity. Nothing under .snip/ is user data, and deleting it while snip is not
running never loses anything.
Editor changes are picked up on the next scan. CLI writes take a library lock
and are atomic, so snip doctor --repair can recover an interrupted one.
FORMAT.md specifies the format normatively, so another tool can read and write a library without going through snip.
Preview and editing
snip edit ID copies the first fragment to a temporary file and opens the
configured editor, then $VISUAL, then $EDITOR, then vi. It checks the
original fingerprint before committing the result. Additional editor targets are
available with --fragment, --note-editor, --readme-editor, and
--metadata-editor.
SnippetsLab migration
The source library is opened read-only. Import is staged, validated, and only then renamed to the requested destination.
The importer preserves snippet and fragment UUIDs, hierarchy, tags, flags, timestamps, content, notes, and original lexer names. Attachments are reported but their private SnippetsLab relationships are not imported in format v1.
Git backup and deletion
Git is optional. snip git status reports the branch, upstream, ahead/behind
counts, uncommitted changes, conflicts, and last commit for the library. File
counts and commits are scoped to the library when it lives inside a larger
repository.
snip init --git only applies at creation time; snip git init makes an
existing library a repository, and is idempotent when it already is one.
commit stages and commits only library content. backup commits when the
library is dirty and pushes whenever the branch is ahead of its upstream, so it
also handles a clean worktree with earlier local commits. push retries only
the push step. fetch refreshes and prunes remote-tracking refs without
changing the worktree. backup is idempotent. These CLI operations are
non-interactive and fail rather than waiting for credentials.
In the TUI, Ctrl-g opens the Git console: b backs up, c commits, p
pushes, f fetches remote status in the background, and C enters a custom
message. Automation is editable there too: i sets the commit interval, u
toggles automatic push, o toggles backup on quit, and a pauses automation
for the current session. In a library that is not yet a repository, i
initializes it.
Automatic behavior is off by default. Set git-auto-commit-interval to make the
TUI create a local commit when the library is dirty and the last commit is at
least that many minutes old. Set git-auto-push to push ahead commits in a
background worker on the same interval. Automatic work skips conflicts, detached
HEADs, in-progress Git operations, open modals, and a library lock held by
another snip process.
snip never pulls, switches branches, or resolves conflicts. If a push is rejected, pull and resolve it in your terminal.
snip delete moves packages into tracked trash/. snip restore moves them
back. Permanent deletion requires snip purge SELECTOR --yes.
Manual pages
Homebrew, deb, rpm, and AUR packages install them, so man snip works right
away. For cargo install or a downloaded archive, install the pages embedded
in the binary:
snip man install warns when the destination is missing from your MANPATH
and prints the line to add. Uninstalling keeps any page you edited yourself.
snip man show snip-create reads a page without installing anything, and
snip man generate DIR exports all of them. Windows has no man; use
snip --help.
Shell completion
Bash, Elvish, and PowerShell are also supported.
Development
Rust 1.89 or newer. Dependencies are pinned in Cargo.lock.
Man pages are generated from the clap command tree and committed in man/.
Update them after changing CLI help, check that they are current, or preview a
page locally:
Main.sniplib/ is a scratch library for development, ignored by the repository.
Recreate it any time with snip init ./Main.sniplib --name Main.
CI
| Workflow | |
|---|---|
CI |
pushes and PRs: fmt, Clippy on both feature sets, tests on Linux (stable, 1.89 MSRV, --no-default-features), macOS arm64, and Windows; checks generated man pages and lints their roff |
Nix |
pushes and PRs: builds the flake on Linux (x86_64, arm64) and macOS, checks the installed layout, and verifies the hashes in nix/package.nix |
Deep tests |
manual: full deterministic suite, importer fixture, watcher regression, coverage |
Release build |
v* tags and manual: builds every platform, then publishes (see below) |
Releasing
- Bump
versioninCargo.toml, then reruncargo run --locked --all-features --example generate-man— the pages embed the version, so CI fails without it. - Add the release to CHANGELOG.md.
- Commit, then tag
vX.Y.Zand push the tag.
The tag is the source of truth: the run fails if it disagrees with Cargo.toml.
It then attaches the platform archives and a signed sniplab-X.Y.Z.tar.gz
source archive to a GitHub release. The AUR package builds from that source
archive and verifies its detached PGP signature.
Before the first release, configure the following repository secrets and
variable. PGP_PRIVATE_KEY must be an ASCII-armored private signing-key export;
keep it and its passphrase out of the repository. PGP_FINGERPRINT is a
repository variable (not a secret) containing the uppercase, whitespace-free
primary-key fingerprint used in the AUR validpgpkeys field.
| Configuration | Purpose |
|---|---|
Secret PGP_PRIVATE_KEY |
ASCII-armored private key used only to sign release source archives |
Secret PGP_PASSPHRASE |
Passphrase for that private key |
Variable PGP_FINGERPRINT |
Public primary-key fingerprint expected by the release workflow and AUR |
It then updates each downstream package, every one gated on its own secret and skipped when that secret is absent:
| Target | Secret |
|---|---|
| crates.io | CARGO_REGISTRY_TOKEN |
| homebrew-snip | HOMEBREW_TAP_TOKEN |
AUR (sniplab) |
AUR_SSH_PRIVATE_KEY |
| scoop-snip | SCOOP_BUCKET_TOKEN |
The workflow rewrites only URLs and checksums, so the tap's own
man1.install Dir["man/*.1"] line is maintained in gitkeniwo/homebrew-snip.
Re-running a release is safe: the crates.io step skips a version already on the registry, and the package updates are no-ops when nothing changed.
License
MIT. See LICENSE.