A powerful CLI tool for managing code snippets with local-first architecture. Store snippets in SQLite with FTS5 full-text search, optional AES encryption, and peer-to-peer sync capabilities.

Features

CRUD Operations: Create, read, update, delete code snippets with ease
Full-Text Search: FTS5-powered search across title, description, code, and tags with ranking
Tag Organization: Flexible tag-based organization with autocomplete
Collections: Group snippets into named collections for better organization
Syntax Highlighting: Beautiful terminal syntax highlighting using Pygments
Import/Export: JSON import/export for backup, sharing, and portability
Encryption: Optional AES encryption for sensitive snippets using PBKDF2 key derivation
P2P Sync: Discover and sync snippets with peers on your local network via mDNS

Installation

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/snippet-manager.git
cd snippet-manager
pip install -e .

Dependencies

click>=8.3.0
cryptography>=46.0.0
pygments>=2.19.0
rich>=13.0.0
zeroconf>=0.148.0

Quick Start

# Initialize the database
snip init

# Add a snippet
snip add --title "Hello World" --code 'print("Hello, World!")' --language python

# List all snippets
snip list

# Get a snippet with syntax highlighting
snip get 1

# Search snippets
snip search hello

# Add tags to organize
snip tag add 1 python basics

# Create a collection
snip collection create "Python Snippets"

# Export snippets for backup
snip export all --file backup.json

# Import snippets from backup
snip import --file backup.json --strategy skip

Commands Reference

Snippet Commands

Command	Description
`snip init`	Initialize the snippet database
`snip add`	Add a new snippet
`snip get <id>`	Get a snippet by ID with syntax highlighting
`snip list`	List all snippets with pagination
`snip edit <id>`	Edit a snippet in your default editor
`snip delete <id>`	Delete a snippet (with confirmation)
`snip search <query>`	Full-text search with FTS5

Tag Commands

Command	Description
`snip tag add <snippet_id> <tag>`	Add a tag to a snippet
`snip tag remove <snippet_id> <tag>`	Remove a tag from a snippet
`snip tag list`	List all tags in use

Collection Commands

Command	Description
`snip collection create <name>`	Create a new collection
`snip collection list`	List all collections
`snip collection delete <id>`	Delete a collection
`snip collection add <collection_id> <snippet_id>`	Add snippet to collection
`snip collection remove <collection_id> <snippet_id>`	Remove snippet from collection

Import/Export Commands

Command	Description
`snip export all --file <path>`	Export all snippets to JSON
`snip export collection <name> --file <path>`	Export a specific collection
`snip export snippet <id> --file <path>`	Export a single snippet
`snip import --file <path> --strategy <strategy>`	Import snippets (strategies: skip, replace, duplicate)

P2P Sync Commands

Command	Description
`snip discover list`	Discover peers on the local network
`snip sync --peer-id <id>`	Sync snippets with a discovered peer
`snip peers`	List known sync peers

Configuration

Environment Variables

Variable	Default	Description
`SNIP_DB_PATH`	`~/.snip/snippets.db`	Path to SQLite database
`SNIP_KEY_FILE`	`~/.snip/.key`	Path to encryption key file
`SNIP_SYNC_PORT`	`8765`	Port for P2P sync
`SNIP_PEER_CACHE`	`~/.snip/peers.json`	Path to peer cache

Configuration File

Optional configuration can be placed at ~/.snip/config.toml:

[database]
path = "~/.snip/snippets.db"

[sync]
port = 8765
auto_discover = true

[display]
style = "monokai"
line_numbers = true

Encryption

Snippets can be encrypted using AES encryption with PBKDF2 key derivation (480k iterations, SHA256).

# Add an encrypted snippet
snip add --title "API Secret" --code "API_KEY=abc123" --language python --encrypt

# View encrypted snippet (will prompt for password)
snip get 1

# Encrypted snippets are stored with is_encrypted flag
# Decryption happens on-demand with password verification

How Encryption Works

User provides a password when creating an encrypted snippet
PBKDF2 derives a 32-byte key using SHA256 (480,000 iterations)
Fernet (AES-128-CBC with HMAC) encrypts the snippet content
Encrypted data stored in database with is_encrypted=True
On retrieval, password decrypts the content in memory

P2P Sync

Snip can discover and sync snippets with other peers on your local network using mDNS/Bonjour service discovery.

Discovery

# Discover available peers on the network
snip discover list

# Output example:
# Peer: macbook-pro.local (192.168.1.100:8765)
# Last seen: 2 minutes ago

Sync Protocol

Peer discovery via _snippets._tcp.local. mDNS service
HTTP/JSON communication over TCP
Sync exchanges snippets updated since last sync
Conflict resolution: newest-wins strategy (with option to keep both)

# Sync with a specific peer
snip sync --peer-id <peer_id>

# View known peers
snip peers

Import/Export Format

Exported JSON follows this structure:

{
  "version": "1.0",
  "exported_at": "2024-01-15T10:30:00Z",
  "snippets": [
    {
      "title": "Hello World",
      "description": "A simple Hello World example",
      "code": "print('Hello, World!')",
      "language": "python",
      "tags": ["basics", "example"],
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Import Strategies

skip: Skip snippets that already exist (by title match)
replace: Replace existing snippets with same title
duplicate: Import all as new snippets (generate new IDs)

Shell Completion

Snip supports shell completion for bash and zsh.

Bash

# Add to ~/.bashrc
eval "$(_SNIP_COMPLETE=bash snip)"

Zsh

# Add to ~/.zshrc
eval "$(_SNIP_COMPLETE=zsh snip)"

Troubleshooting

Database Locked

If you see "Database locked" errors:

Ensure no other snip processes are running
Check file permissions on ~/.snip/

FTS Query Syntax Error

FTS5 uses special syntax for boolean queries:

Use quotes for phrases: "hello world"
Use AND/OR for boolean: hello AND world
Escape special characters with \

Decryption Failed

Verify you're using the correct password
Passwords cannot be recovered if forgotten
Encrypted snippets without the password cannot be decrypted

Peer Unreachable

Ensure both peers are on the same network
Check firewall settings for port 8765
Verify mDNS/Bonjour is enabled on your system

Development

# Clone repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/snippet-manager.git
cd snippet-manager

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with verbose output
pytest tests/ -v --capture=no

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or submit a pull request.