snippets-cli (snip)

CLI for your snippet and prompt library: code snippets, LLM prompts, and reusable content — with semantic search, Obsidian-compatible markdown storage, and LLM enrichment.

What you can store

• 📋 Code snippets — boilerplate, helpers, and reference fragments (by language)
• 💬 Prompt library — system prompts, instruction templates, and AI prompts with {{variable}} or {{variable|default}} placeholders; run with snip run <name> and pass variables at use time
• 🏷️ Custom types — add your own (e.g. checklists, templates, agents) via snip config:types:add <name>

Features

• 📁 Local-first markdown storage — Obsidian-compatible, plain files you own
• 🔍 Semantic search via qmd vector embeddings
• 🤖 BYOL (Bring Your Own LLM) — auto-generate title, description, tags, and language with your choice of Ollama, Gemini, Claude, or OpenAI
• 💬 Prompt templates — first-class prompts/ type and {{var}} / {{var|default}} syntax; snip run fills variables
• ⌘ Alfred workflow integration for macOS
• ⚡ Shell completions for bash, zsh, and fish
• 📥 Import from files, globs, URLs, or GitHub Gists
• 📤 Export to JSON, Markdown, or GitHub Gists
• 🔄 Gist sync — bidirectional sync between local snippets and GitHub Gists

Installation

npm install -g @jtsternberg/snip

Requires Node.js 22+.

From source

git clone https://github.com/jtsternberg/snippets-cli.git
cd snippets-cli
npm install
npm run build
npm link

Quick Start

snip init                          # Initialize library at ~/snippets
snip add --from-clipboard          # Add snippet from clipboard
snip add --type prompts --title "Code review" --lang prompt  # Add to prompt library
snip add --title "My Script" --lang bash  # Add with metadata
snip search "api helper"           # Semantic search
snip run my-prompt -- language=TypeScript  # Run prompt template with variables
snip exec git-diff-name-only-from-branch   # Use placeholder defaults inside command snippets
snip copy my-snippet               # Copy to clipboard
snip show my-snippet               # Display in terminal

Commands

| Command | Description | | --- | --- | | snip init | Initialize snippet library and config | | snip add | Add a new snippet (interactive or scripted, --provider) | | snip show <name> | Display snippet (--raw, --code) | | snip copy <name> | Copy snippet to clipboard | | snip edit <name> | Open snippet in editor | | snip rm <name> | Delete a snippet | | snip list | List snippets (--type, --tag, --lang, --json) | | snip tags | List all tags | | snip search <query> | Semantic search (--json, -n, --mode) | | snip find <query> | Fuzzy text search | | snip rename <name> <new-name> | Rename a snippet | | snip run <name> | Fill template variables and copy result (--var key=value) | | snip exec <name> [args...] | Execute a snippet as a script (--shell, --dry-run); positional args are passed to the script (use -- before args starting with -) | | snip link <name> | Create symlink to snippet | | snip import [sources...] | Import from files, globs, URLs, or gists (--from-gist, --provider) | | snip export [name] | Export to JSON, Markdown, or GitHub Gist (--to-gist, --public) | | snip enrich [name] | Re-run LLM enrichment (--all, --force, --dry-run, --provider) | | snip sync | Sync gist-linked snippets (--push, --pull, --dry-run) | | snip config | View or set configuration | | snip config:types:add <name> | Add a snippet type | | snip config:llm | View LLM provider configuration | | snip config:llm:provider <name> | Set primary LLM provider | | snip config:llm:fallback <name> | Set fallback LLM provider | | snip config:llm:key <provider> <key> | Set API key for a provider | | snip config:llm:model <provider> <model> | Set model for a provider | | snip install <integration> | Install integrations (completions, alfred, obsidian) | | snip upgrade | Update snip and reinstall integrations | | snip doctor | Health check |

Configuration

Config file: ~/.config/snip/config.json

| Setting | Description | Default | | --- | --- | --- | | libraryPath | Path to snippet library | ~/snippets | | types | Snippet type directories | ["snippets", "prompts"] | | defaultType | Default type for new snippets | — | | editor | Editor for snip edit (falls back to $EDITOR) | — | | llm.provider | LLM provider (ollama, gemini, gemini-cli, claude, claude-cli, openai, openai-cli, auto) | "ollama" | | llm.fallbackProvider | Fallback provider (same options, or null) | null | | llm.ollamaModel | Ollama model | "qwen2.5-coder:7b" | | llm.ollamaHost | Ollama API host | "http://localhost:11434" | | llm.geminiApiKey | Gemini API key (or use GEMINI_API_KEY env var) | null | | llm.geminiModel | Gemini API model | "gemini-2.5-flash" | | llm.geminiCliModel | Gemini CLI model (when using gemini-cli) | "gemini-2.5-flash" | | llm.anthropicApiKey | Anthropic API key (or use ANTHROPIC_API_KEY env var) | null | | llm.anthropicModel | Claude API model | "claude-3-5-haiku-latest" | | llm.claudeCliModel | Claude CLI model (when using claude CLI) | "haiku" | | llm.openaiApiKey | OpenAI API key (or use OPENAI_API_KEY env var) | null | | llm.openaiModel | OpenAI API model | "gpt-4o-mini" | | llm.codexCliModel | OpenAI CLI model (when using openai-cli) | "o4-mini" | | qmd.collectionName | qmd collection name | — | | alfred.maxResults | Max Alfred results | — |

Environment Variables

• SNIP_LIBRARY — Override library path
• EDITOR — Fallback editor
• GEMINI_API_KEY — Gemini API key (overrides config)
• ANTHROPIC_API_KEY — Anthropic/Claude API key (overrides config)
• OPENAI_API_KEY — OpenAI API key (overrides config)

Snippet Format

Snippets are stored as markdown files with YAML frontmatter:

---
title: API Request Helper
description: Fetch wrapper with error handling
tags:
  - javascript
  - api
aliases:
  - fetch-helper
language: javascript
type: snippets
date: "2026-03-09"
modified: "2026-03-09"
source: ""
related:
  - "[[error-handling]]"
---

```javascript
async function apiRequest(url, options = {}) {
  const response = await fetch(url, options);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

The `related` field uses Obsidian-style wikilinks for cross-referencing. For prompts, set `type: prompts`, use `language: prompt` and optional `{{variable}}` or `{{variable|default}}` placeholders in the body; use `snip run <name> --var key=value` to fill and run them. Command snippets executed with `snip exec` can use the same syntax for positional arguments with defaults.

## Integrations

### Alfred Workflow

```bash
snip install alfred

• snip keyword — search snippets
• Enter — paste snippet
• Cmd+Enter — copy to clipboard
• Alt+Enter — open file
• Ctrl+Enter — reveal in Finder
• snipsaveclipboard keyword — save clipboard as a new snippet

Shell Completions

snip install completions        # Auto-detect shell
snip install completions zsh    # Specific shell

Obsidian

snip install obsidian

Opens your snippet library as an Obsidian vault. Snippets use wikilinks in related fields for cross-referencing.

GitHub Gist Sync

Export snippets as GitHub Gists and keep them in sync. Requires the GitHub CLI (gh).

snip export my-snippet --to-gist          # Create a secret gist
snip export my-snippet --to-gist --public # Create a public gist
snip export my-snippet --to-gist          # Re-run to update existing gist
snip import --from-gist <gist-url-or-id>  # Import all files from a gist
snip sync                                 # Sync all gist-linked snippets
snip sync --dry-run                       # Preview what would sync
snip sync --push                          # Force push local changes
snip sync --pull                          # Force pull gist changes

Gist-linked snippets track their gist_id and gist_updated timestamp in frontmatter for automatic sync detection.

Semantic Search (qmd)

Install qmd for semantic/vector search:

npm i -g @tobilu/qmd

BYOL: Bring Your Own LLM

Snip uses an LLM to auto-generate metadata (title, description, tags, language, aliases) when you add or import snippets. Choose from four providers:

Ollama (default — local, free):

brew install ollama
ollama pull qwen2.5-coder:7b

Gemini (cloud):

snip config:llm:provider gemini
snip config:llm:key gemini YOUR_API_KEY
# or: export GEMINI_API_KEY=YOUR_API_KEY

Claude (cloud API or local CLI):

snip config:llm:provider claude
snip config:llm:key claude YOUR_API_KEY
# or: export ANTHROPIC_API_KEY=YOUR_API_KEY
# If no API key, falls back to the `claude` CLI if installed

OpenAI (cloud):

snip config:llm:provider openai
snip config:llm:key openai YOUR_API_KEY
# or: export OPENAI_API_KEY=YOUR_API_KEY

Auto mode — tries CLI tools first (gemini-cli, claude-cli, openai-cli), then Ollama, then cloud APIs (Gemini, Claude, OpenAI) until one succeeds:

snip config:llm:provider auto

Re-enrich existing snippets after switching providers:

snip enrich my-snippet          # Single snippet
snip enrich --all               # All snippets with missing metadata
snip enrich --all --force       # Regenerate all metadata

Claude Code Plugin

This repository includes a Claude Code plugin for AI-assisted snippet management. Add, search, and organize snippets using natural language.

Quick Example

You: "Save this as a prompt in my prompt library"
You: "Save this function to my snippets with tags js and util"
You: "Find all my Python snippets about error handling"
You: "Run my code-review prompt template with language=TypeScript"

Installation

In Claude Code:

/plugin marketplace add jtsternberg/snippets-cli
/plugin install snippets-cli

Or point to your existing copy of the snippets-cli repository:

/plugin marketplace add ./snippets-cli
/plugin install snippets-cli

Features

• Skills: Auto-invoked when discussing snippets, code fragments, or prompt templates
• Commands: /snippets-cli:add, /snippets-cli:find, /snippets-cli:show
• Agent: Snippet specialist for complex multi-step workflows

See claude-plugin/.claude-plugin/README.md for full documentation.

Development

npm run dev          # Watch mode
npm test             # Run tests
npm run build        # Build for production
npm run typecheck    # Type checking

License

MIT