snip
every command for this project, zero memorization

---

🎯 Why snip?

Before:

README → find command → copy → paste → switch back → run

After:

$ snip dev
→ npm run dev

That's it. One command. No memorization, no scrolling history, no Slack-ing coworkers.

---

snip saves project-scoped command snippets in a committable .snips file. Run snip to list them. Run snip run <name> to execute them. Run snip "start frontend" to run by natural language. No memorization. No config.

Every project has commands you always forget. "What's the deploy command?" "How do I seed the database?" snip fixes that — and once you commit .snips to git, every teammate gets the same commands automatically.

What makes snip different

	snip	npm run	make	just	pet
Project-scoped & committable	✅ .snips in repo	✅ package.json	✅ Makefile	✅ justfile	❌ global only
Fuzzy matching built-in	✅ always available	❌	❌	⚠️ requires fzf	⚠️ requires fzf
Human-friendly format	✅ TOML	⚠️ JSON	⚠️ tab-indented	⚠️ custom syntax	✅ TOML
Auto-detects existing commands	✅ 11 file types	N/A	N/A	❌	❌
Zero config	✅ snip init	✅	✅	✅	❌
Variable substitution	✅ {{var}} prompts	❌	⚠️ make vars	✅ recipe vars	❌
Global snippets	✅ ~/.config/snip/global.toml	❌	❌	❌	✅
Team sharing	✅ commit .snips + gist import	✅	✅	✅	❌ gist-based
Cold start	< 5 ms	~150 ms	~50 ms	~30 ms	~200 ms
Binary size	~1.6 MB	N/A	~400 KB	~4 MB	~8 MB

---

📦 Install

From crates.io (recommended)

cargo install snipit

The package is published as snipit because snip was already taken on crates.io. The binary is still installed as snip.

From source

git clone https://github.com/Bilal140202/snip.git
cd snip
cargo install --path .

Binary download

Pre-built binaries for Linux, macOS, and Windows are available on the Releases page:

# Linux (x86_64)
curl -sL https://github.com/Bilal140202/snip/releases/latest/download/snip-x86_64-linux.tar.gz | tar xz

# macOS (Apple Silicon)
curl -sL https://github.com/Bilal140202/snip/releases/latest/download/snip-aarch64-macos.tar.gz | tar xz

Homebrew

brew install Bilal140202/snip/snip

---

🚀 Quick Start

# 1. Navigate to any project
cd your-project

# 2. Auto-detect commands from package.json, Makefile, Cargo.toml, etc.
snip init
# ✅ Created .snips with 8 commands from npm

# 3. List all commands — grouped by section
snip
#   dev            Start dev server on :3000
#   test           Run tests
#   test:watch     Run tests in watch mode
#   build          Build for production
#   lint           Run ESLint

# 4. Run any command by name (or fuzzy match)
snip run dev
# → npm run dev

snip run tst          # fuzzy match — "did you mean test?"
# → npm test

# 5. Commit .snips so every teammate gets your commands
git add .snips && git commit -m "add snip commands"

---

📋 Commands

Command	Description
snip	List all snippets, grouped by section
snip init	Auto-detect commands and scaffold .snips
snip add <name> "<cmd>" [desc]	Add a new snippet
snip rm <name>	Remove a snippet
snip rename <old> <new>	Rename a snippet (preserves all metadata)
snip mv <name> <section>	Move a snippet to a different section
snip edit	Open .snips in $EDITOR
snip list	List snippets (alias: snip ls)
snip search <query>	Full-text search across snippets
snip tag <tag> [--run <name>]	List snippets by tag, optionally run one
snip run <name> [--dry-run]	Execute a snippet (supports fuzzy matching)
snip "<phrase>"	Execute by natural language (e.g. snip "deploy staging")
snip export <name>	Copy a snippet to clipboard (TOML or --format cmd)
snip import <path-or-url>	Import from .snips file or GitHub gist URL
snip doctor	Validate snippets + check env vars, Docker, .env presence
snip completions <shell>	Generate shell completions (bash/zsh/fish/nushell)
snip hook	One-line shell setup — completions + keybindings
snip suggest	Analyze shell history and suggest snippet candidates
snip explain <name>	Break down what a snippet command does
snip stale	Detect unused or outdated snippets
snip setup	Full project bootstrap: install deps, create .env, build, test, dev

---

📄 .snips File Format

A TOML file that lives in your project root. Commit it to git.

format = "1.0"

[dev]
cmd = "npm run dev"
desc = "Start dev server on :3000"

[test]
cmd = "npm test -- --watch"
desc = "Run tests in watch mode"
tags = ["ci", "qa"]

[build]
cmd = "npm run build"
desc = "Build for production"
dir = "frontend"                     # run from a subdirectory

[deploy.staging]
cmd = "fly deploy --app myapp-staging"
desc = "Deploy to staging environment"

[deploy.production]
cmd = "fly deploy --app myapp-production"
desc = "Deploy to production"
tags = ["deploy", "release"]

[lint.fix]
cmd = "npx eslint --fix 'src/**/*.{ts,tsx}'"
desc = "Auto-fix lint issues"
shell = "bash"                       # explicit shell override

[db.reset]
cmd = "docker compose down -v && docker compose up -d && npm run db:migrate"
desc = "Nuke and rebuild local database"
tags = ["db"]

[release]
cmd = "gh release create {{version}} --title {{version}} --notes-from-tag"
desc = "Create a GitHub release"
vars = [
  { name = "version", desc = "Release version (e.g. 1.2.0)" }
]

Features at a glance

Feature	Syntax
Sections	[deploy.staging] — dot-notation creates nested groups
Descriptions	desc = "..." — shown in snip list and completions
Tags	tags = ["deploy", "release"] — for filtering
Variables	vars = [{ name = "env", ... }] with {{env}} placeholders
Shell override	shell = "bash" — run in a specific shell
Working directory	dir = "frontend" — run from a subdirectory
Version lock	format = "1.0" — forward-compatibility header

---

🔗 Shell Integration

Add one line to your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish:

eval "$(snip hook)"

That's it. This enables:

• Dynamic tab completions — snippet names update when you edit .snips
• Keybindings (future) — Ctrl+S to open the snippet picker from anywhere

Manual completion setup (alternative)

# Bash
eval "$(snip completions bash)"

# Zsh
eval "$(snip completions zsh)"

# Fish
snip completions fish | source

# Nushell
snip completions nushell | save -f ~/.cache/snip/completions.nu

---

✨ Variable Substitution

Snippets support {{variable}} placeholders. When you run one, snip prompts you for values:

[deploy]
cmd = "kubectl apply -f k8s/{{env}}/ --namespace {{ns}}"
desc = "Deploy to environment"
vars = [
  { name = "env", desc = "Target environment", options = ["staging", "production"] },
  { name = "ns", desc = "Kubernetes namespace", default = "default" }
]

$ snip run deploy

  ? env: Target environment (staging, production): staging
  ? ns: Kubernetes namespace (default): myapp

  → kubectl apply -f k8s/staging/ --namespace myapp

Features:

• Options — restrict to a list of allowed values
• Defaults — skip the prompt by providing a default value
• Space-tolerant — {{ var }} and {{var}} both work

---

🔍 Fuzzy Matching

You don't need to remember exact snippet names. snip uses fuzzy matching to find what you mean:

$ snip run tst       # matches "test"
$ snip run dply stg  # matches "deploy.staging"
$ snip run bld       # matches "build"

If nothing matches closely, snip suggests the closest alternative:

  ✗ No snippet found for "tset"
  → Did you mean "test"?

When fzf is installed, snip list opens an interactive picker automatically. Select and press Enter to run.

---

🧠 Advanced Features

.snips.d/ Directory

For teams and larger projects, split snippets into modular files:

.snips                 # base snippets
.snips.d/
  common.toml          # shared commands
  frontend.toml        # frontend team commands
  backend.toml         # backend team commands
  local.toml           # personal (git-ignored) snippets

Files are merged with a priority chain — later files override earlier ones. Add local.toml to .gitignore for personal snippets that don't get committed.

snip suggest — History-Based Suggestions

Analyzes your shell history to find frequently-run commands not yet in .snips:

$ snip suggest
  💡 You run this often but it's not in .snips:
    1. npm run test:watch   (ran 47 times)
    2. docker compose up -d (ran 23 times)

  Add them? (y/n)

snip explain — Command Breakdown

Understand what a snippet does before running it:

$ snip explain db.reset

  docker compose down -v     # Stop all containers and remove volumes
  &&                         # then
  docker compose up -d       # Start containers in detached mode
  &&                         # then
  npm run db:migrate         # Run database migrations

snip stale — Detect Unused Snippets

Find snippets that haven't been run in a while:

$ snip stale
  ⚠ These snippets haven't been run in 30+ days:
    - legacy.build    (last run: 92 days ago)
    - old.lint        (last run: never)

JSON Output Mode

Pipe snippet data to other tools:

$ snip list --json
[
  {"key":"dev","cmd":"npm run dev","desc":"Start dev server on :3000"},
  {"key":"test","cmd":"npm test","desc":"Run tests"}
]

$ snip list --format "{{key}}: {{cmd}}"
dev: npm run dev
test: npm test

Auto-Detection

snip init detects commands from your existing project files (11 file types):

File	What it detects
package.json	npm scripts
Makefile	.PHONY targets with ## descriptions
Cargo.toml	Common cargo commands (build, test, run, clippy)
pyproject.toml	PDM / project scripts
docker-compose.yml	Service names
go.mod	Common go commands (build, test, run, fmt, vet, mod)
deno.json / deno.jsonc	Deno tasks (with comment-stripping for JSONC)
Taskfile.yml / Taskfile.yaml	Top-level tasks
justfile / Justfile	Recipes with # doc comments
Rakefile	Tasks with desc "..." or # doc comments
mix.exs	Common mix commands (compile, test, fmt, deps, phx, ecto, release)

Running snip with no .snips file auto-detects and offers to create one.

---

🚀 Project Onboarding

snip setup is a one-command project bootstrap — point a new teammate at a fresh clone and they're productive immediately:

git clone https://github.com/yourorg/yourproject.git
cd yourproject
snip setup

Seven steps run in order:

1. check-tools — detect Node/Rust/Go/Python/Docker/etc. from project files
2. install-deps — pnpm install / cargo fetch / go mod download (auto-detected from lockfiles)
3. create-env — copy .env.example → .env, or generate a template from env vars referenced in snippets
4. start-services — docker compose up -d if docker-compose.yml exists
5. build — run the project's build command
6. test — run the project's tests
7. dev — start the dev server in the foreground

# Skip specific steps:
snip setup --skip=build,test

# Run only specific steps:
snip setup --only=install-deps,create-env

# Non-interactive (CI mode):
snip setup --non-interactive

# Dry-run (show what would happen):
snip setup --dry-run

Each step prefers a snippet tagged ["setup"] whose key matches the step name, falling back to auto-detected commands. This lets teams customize setup without config files:

[install-deps]
cmd = "pnpm install --frozen-lockfile"
desc = "Install dependencies"
tags = ["setup"]

[build]
cmd = "turbo build"
desc = "Build all packages"
tags = ["setup"]

---

🛠 Development

# Build
cargo build --release

# Test (469 tests)
cargo test

# Install locally
cargo install --path .

# Lint (CI gate)
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

# Run with debug output
RUST_LOG=debug cargo run -- run dev

Contributions welcome! See CONTRIBUTING.md for guidelines.

---

📄 License

MIT © 2025-present