Stashpad

Stashpad is a personal developer reference manager (stash on the command line).

Save URLs, shell commands, code snippets, and notes. Tag them, search, export, and browse from the terminal.

Full reference: docs/

How it works

Stashpad is a local, searchable cheat sheet for developers. You save things you look up repeatedly — shell commands, snippets, URLs, notes — and find them again from the terminal.

Data storage

Everything lives in a single JSON file:

~/.config/stash/vault.json    # default location

Override with STASH_DATA_DIR, --config-dir, or a path passed to stash init. The file contains:

• Entries — title, content, optional URL, tags, priority, kind, pinned flag, timestamps, UUID
• Tags — a registry of tag names used in the vault

Example scripts use examples/.demo-vault/ so they never touch your real vault.

Typical workflow

stash init --name my-vault                         # create vault once
stash entry add "Docker prune" "docker ..." --tag devops
stash add "Quick note" "echo hello"              # top-level alias
git log -5 | stash add "Recent commits" -      # pipe into vault
stash pins                                       # pinned favorites
stash pick deploy --copy                         # interactive picker
stash browse                                     # split-pane TUI (poetry install -E tui)
stash search "prune"                             # fuzzy ranked search
stash entry copy <id> --first-line               # copy command to clipboard
stash entry run <id>                             # run with confirmation
stash export json ./backup.json                  # backup
stash import --from-file ./backup.json           # restore

Useful global flags: --json (scripting), --verbose, --config-dir (alternate vault).

Validation with Pydantic

Input is validated before it hits disk:

Schema	Used for
EntryCreate	New entries (title, URL, tags normalized)
EntryUpdate	Partial edits
EntryFilter	List/search filters
ImportPayload	JSON import files

Invalid URLs, empty titles, or malformed import files fail early with clear errors.

Architecture

CLI commands  ──►  storage.py  ──►  vault.json
                        ▲
                        │
                  models / schemas (Pydantic)

Quick start

pip install stashpad
# or: pipx install stashpad

stash init --name my-vault

stash entry add "Docker prune" "docker system prune -af" \
  --tag devops --tag docker --url https://docs.docker.com

stash entry list --tag devops
stash search "prune"
stash --json entry list

AI assistants

Connect your vault to coding assistants, or teach them Stashpad workflows:

MCP (recommended) — lets the assistant search your vault while you code:

pip install "stashpad[mcp]"
stash init --name my-vault

Then configure MCP in Cursor or Claude Desktop — see docs/mcp.md.

Agent skills (optional) — workflow guides for setup, capture, search, backup, and MCP config:

Client	Install
Cursor / Codex	Clone repo → ./install.sh install --ide cursor → restart Cursor
Claude Code	claude plugin marketplace add Vicba/stashpad → claude plugin install stashpad@stashpad
Claude Desktop	MCP only — no skills plugin; see docs/mcp.md

install.sh is in the repo, not on PyPI. Full guide: docs/agent-skills.md.

From source:

git clone https://github.com/Vicba/stashpad.git
cd stashpad
poetry install
poetry install -E tui   # optional: split-pane browse UI
poetry install -E mcp   # optional: MCP server for Cursor / Claude Desktop
poetry run stash init --name my-vault

CLI commands

Command	Description
stash init	Initialize vault (prompts, env vars)
stash add	Quick-capture alias for stash entry add (stdin, clipboard)
stash entry add/list/show/edit/remove/copy/run/pin/unpin	CRUD with UUID, enums, filters, aliases (ls, rm)
stash pins	List pinned favorites
stash pick	Interactive fzf-style picker (--copy, --run, --open)
stash browse	Split-pane TUI browser (poetry install -E tui)
stash search	Fuzzy ranked search (--exact to disable)
stash mcp serve	MCP server for AI assistants (poetry install -E mcp, Python 3.10+)
stash tags list/add/remove	Nested subcommands
stash export json/markdown	Export with Path types and progress bars
stash import	Import from JSON files
stash open	Open entry URL in browser
stash config show/set/path	Configuration management

Global flags: --verbose, --json, --config-dir, --version

Run poetry run stash --help for full usage.

Examples

Runnable walkthroughs and sample data live in examples/:

./examples/scripts/01-getting-started.sh
./examples/scripts/04-import-export.sh

Development

poetry run poe test      # run tests
poetry run poe lint      # lint
poetry run poe dev       # dev runner

Dev Container

For contributors: open the repo in VS Code or Cursor and choose Reopen in Container. See docs/devcontainer.md for rebuild, exit, and testing notes.

Project structure

src/stashpad/         # Python CLI, TUI, MCP server
plugins/stashpad/     # Agent skills plugin (6 skills)
.devcontainer/        # Contributor dev container
docs/                 # Reference documentation
install.sh            # Install skills to Cursor, Codex, Antigravity
AGENTS.md             # Repo-level agent guidance
tests/                # CLI tests

License

MIT