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:

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

From source:

git clone https://github.com/Vicba/stash-cli.git
cd stash-cli
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

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

Project structure

src/stashpad/
  cli.py              # root app + global callback
  context.py          # shared AppContext
  models.py           # Entry, Vault, enums
  storage.py          # JSON persistence (~/.config/stash/)
  commands/           # one module per command group
  mcp/                # MCP service + FastMCP server
docs/                 # Reference documentation
tests/                # CLI tests

License

MIT