DevVault CLI

Save code snippets, bookmarks, prompts, and shell commands to your DevVault dashboard — right from the terminal.

Installation

npm install -g devvault-cli

Quick Start

dv auth login                    # paste an API key from the dashboard
dv save "git push origin main"   # save a command
dv save --from-history           # pick from recent terminal history
dv search "docker"               # search your vault
dv hook install                  # enable auto-tracking

---

Commands

Authentication

DevVault authenticates with an API key. Generate one in the dashboard (Settings → API Keys), then paste it into the CLI. There is no password login — keys are long-lived, revocable, and safe to use in scripts/CI.

Command	Description	Example
dv auth login	Paste an API key (hidden prompt; verified before saving)	dv auth login
dv auth login --api-url <url>	Point at a specific API and persist it	dv auth login --api-url http://localhost:4000/api/v1
dv auth logout	Clear the stored key	dv auth logout
dv auth status	Show who you're logged in as	dv auth status
dv auth token <key>	Set a key non-interactively (CI/scripts)	dv auth token dv_live_…

You can also skip login entirely and set DEVVAULT_TOKEN=dv_live_… in the environment (ideal for CI). Piping works too: echo "$KEY" | dv auth login.

Save

Command	Description	Example
dv save <content>	Save inline content	dv save "npm run build"
dv save	Open interactive editor	dv save
dv save --from-history [n]	Pick from recent ZSH history	dv save --from-history 30
dv save --frequent	Save commands run 3+ times in 30 days	dv save --frequent
dv save --repeated	Save commands repeated in last hour	dv save --repeated
dv save --clip	Save from clipboard	dv save --clip

Options:

Flag	Description
--type <type>	Force type: cmd, snippet, bookmark, prompt
--title <title>	Set a custom title
--tag <tag>	Add a tag (repeatable: --tag node --tag docker)
-y, --yes	Skip confirmation prompts
--silent	No output (for scripting)

Search

Command	Description	Example
dv search <query>	Search your vault	dv search "react hooks"
dv search --local <query>	Fuzzy search local history (offline)	dv search --local "docker"
dv search --type cmd <query>	Filter by type	dv search --type cmd "deploy"
dv search --tag <tag> <query>	Filter by tag	dv search --tag docker "compose"

History

Command	Description	Example
dv history	Show recent items from vault	dv history
dv history --unsaved	Show unsaved local commands	dv history --unsaved
dv history --stats	Show local tracking statistics	dv history --stats
dv history --type cmd	Filter by type	dv history --type cmd

Hook Management

Command	Description
dv hook install	Install ZSH hook into ~/.zshrc
dv hook uninstall	Remove ZSH hook from ~/.zshrc
dv hook status	Check hook status + tracked command count

Other

Command	Description
dv open	Open the DevVault dashboard in browser
dv --version	Show CLI version
dv --json	Output raw JSON (pipe to jq)

---

Saving Commands — All 6 Ways

Method	Command	When to use
Inline	dv save "git push"	One command, right now
Pipe	history | tail -1 | dv save	From another command's output
From history	dv save --from-history	Browse and pick from recent history
Frequent	dv save --frequent	Commands you run often (3+ times in 30d)
Auto-nudge	ZSH hook + dv save --repeated	Automatic prompts when you repeat commands
Clipboard	dv save --clip	Save whatever's in your clipboard

---

ZSH Hook

The ZSH hook silently tracks your terminal commands in the background. It never blocks your prompt or slows down your terminal.

Install

dv hook install
source ~/.zshrc    # activate immediately

Verify

devvault_hook_status
# or
dv hook status

How it works

1. The hook captures every command you run (except ignored ones like cd, ls, clear)
2. Commands are logged to ~/.devvault/zsh-history.json in the background
3. When a command is run 5+ times in a day, you'll see a subtle nudge
4. Use dv save --from-history or dv save --frequent to vault the ones you want

Uninstall

dv hook uninstall
source ~/.zshrc

Note: Your tracked history at ~/.devvault/zsh-history.json is preserved after uninstall.

Compatibility

The hook uses add-zsh-hook and runs in the background — it's safe alongside:

• Oh My Zsh
• Starship
• Powerlevel10k
• Any other ZSH framework

---

Environment Variables

Variable	Description
DEVVAULT_API_URL	Override API endpoint (default: https://api.devvault.io)
DEVVAULT_TOKEN	Token for CI/headless environments (skip dv auth login)
DEVVAULT_DEBUG	Set to 1 to show stack traces on errors

---

Architecture

Your terminal → ZSH hook → ~/.devvault/zsh-history.json
                                     ↓
dv save --frequent / --from-history / --repeated
                                     ↓
                        DevVault API → Dashboard

devvault-cli/
├── bin/dv.js              ← entry point
├── src/
│   ├── commands/
│   │   ├── auth.js         ← login / logout / status / token
│   │   ├── save.js         ← save (5 input modes)
│   │   ├── search.js       ← search vault + local fuzzy
│   │   ├── history.js      ← history + stats
│   │   └── hook.js         ← hidden _hook (background logging)
│   ├── lib/
│   │   ├── api.js          ← axios HTTP client
│   │   ├── config.js       ← ~/.devvault/config.json
│   │   ├── detector.js     ← auto-classify content type
│   │   └── tracker.js      ← ZSH history data layer
│   └── hooks/
│       └── install.js      ← install/uninstall ZSH hook
├── shell/
│   └── devvault.zsh        ← ZSH hook script
└── package.json

---

License

MIT