codecache-cli

Local-first CLI for storing and retrieving code snippets in a SQLite vault.

codecache-cli is built for humans and coding agents that need a simple local snippet database with a stable CLI, machine-friendly output, and no hosted service dependency.

Why

• store reusable code snippets in a local SQLite database
• search across code, title, notes, description, and tags
• attach local files to snippets
• script it from agents with JSON output
• keep everything in a user-controlled local vault

Features

• SQLite-only local vaults
• snippet create, get, list, search, update, delete
• code-aware search with FTS5
• tag support
• file attachments stored alongside the vault
• stdin support for snippet creation
• human, json, and jsonl output modes
• explicit --yes safety for destructive deletes

Install

After install, the command is cache.

Install paths:

Homebrew

brew tap tanRdev/homebrew-tap
brew install codecache-cli

Curl installer

curl -fsSL https://raw.githubusercontent.com/tanRdev/codecache-cli/main/scripts/install.sh | bash

The installer downloads the latest GitHub release tarball and installs cache into ~/.local/bin by default.

Agent skill

Install the reusable skill for AI agents through skills.sh:

npx skills add https://github.com/tanRdev/codecache-cli --skill codecache-cli

This gives your coding agent native capabilities for storing, searching, and managing snippets in the local vault.

Quick Start

Initialize a vault and save it as the default:

cache init --vault ~/codecache --set-default

Add a snippet from a file:

cache add src/reducer.ts --title "Reducer helper" --tag react --tag forms

Add a snippet from stdin:

pbpaste | cache add - --title "Clipboard snippet" --language typescript

Search snippets:

cache search createReducer
cache snippet list react --limit 5

Get a snippet:

cache get <snippet-id>
cache get <snippet-id> --raw

Attach a file:

cache attachment add <snippet-id> ./notes.md
cache attachment list <snippet-id>
cache attachment get <attachment-id> --output ./exported-notes.md

Delete safely:

cache attachment delete <attachment-id> --yes
cache rm <snippet-id> --yes

Vault Model

A vault is a directory containing:

• cache.sqlite
• attachments/

Vault resolution order:

1. --vault PATH
2. CACHE_CLI_VAULT
3. saved default vault from local config

Read commands require an initialized vault. They do not create missing paths implicitly.

Commands

cache init --vault PATH [--set-default]
cache status [--vault PATH]
cache vault show
cache vault use PATH

cache snippet create [FILE|-] --title ... [--language ...] [--tag ...]
cache snippet list [QUERY] [--tag TAG] [--limit N]
cache snippet get ID [--raw]
cache snippet update ID [FILE|-] [--title ...] [--language ...] [--tag ...]
cache snippet delete ID --yes

cache add [FILE|-] ...
cache search [QUERY] ...
cache get ID ...
cache rm ID --yes

cache tags

cache attachment add SNIPPET_ID FILE
cache attachment list SNIPPET_ID
cache attachment get ATTACHMENT_ID --output PATH
cache attachment delete ATTACHMENT_ID --yes

Output Modes

• TTY default: human
• non-TTY default: json
• optional: --format jsonl

cache get --raw prints raw snippet code directly.

Agent Usage

This CLI is designed to be agent-friendly.

Examples:

cache search "agentCacheValue" --format json
cache snippet list util --limit 10 --format json
cache get <snippet-id> --raw

Recommended agent patterns:

• use --format json for structured reads
• use --raw when you need only snippet code
• pass --vault PATH explicitly in multi-project automation

Distribution

• Homebrew formula: tanRdev/homebrew-tap/codecache-cli
• GitHub releases: binary-installable tarball assets

License

MIT