CLI (pnote)

pnote is the PromptNote CLI. Search notes, copy snippets to clipboard, create content from stdin, and pipe output to other tools.

Installation

Requires Node.js 18 or later.

npm install -g pnote

Authentication

Generate an API token from the web app, then:

pnote auth token pn_your_token_here

# Verify
pnote auth whoami

Or set the environment variable:

export PNOTE_TOKEN=pn_your_token_here

Commands

Notes

pnote notes                    # List all notes
pnote notes --tag "AI/art"     # Filter by tag
pnote notes --archived         # Show archived
pnote notes --deleted          # Show deleted
pnote notes --pinned           # Show pinned only
pnote notes --protected        # Show only PIN-protected notes
pnote notes --search "query"   # Search by title
pnote notes get <id>           # Get note details
pnote notes get <id> --latest  # Get note with latest snippet only
pnote notes create "Title"     # Create new note
pnote notes update <id> --title "New Title"
pnote notes update <id> --tags a b c
pnote notes archive <id>       # Archive note
pnote notes archive <id> --undo  # Unarchive note
pnote notes pin <id>           # Toggle pin
pnote notes delete <id>        # Soft delete

Notes are listed 50 at a time. Use --limit <n> and --offset <n> for pagination, or --all to fetch every matching note. The 8-character id shown in tables is accepted anywhere a note id is expected (an ambiguous prefix is refused).

Snippets

pnote notes snippet <note-id>                        # Show latest snippet (pipe-friendly)
pnote notes snippet list <note-id>                   # List all versions
pnote notes snippet copy <note-id>                   # Copy to clipboard
pnote notes snippet copy <note-id> --version 2     # Copy a specific version
echo "content" | pnote notes snippet add <note-id>      # Add version from stdin
echo "updated" | pnote notes snippet update <snippet-id> # Update existing
pnote notes snippet favorite <snippet-id>                 # Toggle favorite

Tags

pnote tags                             # List all tags with counts
pnote tags --include-archived        # Include tags from archived notes
pnote tags rename "old" "new"          # Rename tag (includes children)
pnote tags merge "a" "b" --into "c"    # Merge tags

Sharing

pnote share tags                       # List shared tags
pnote share tags <id>                  # View notes in shared tag
pnote share tags <id> --limit 10       # Limit notes returned
pnote share notes                      # List public share links
pnote share notes --include-revoked    # Include revoked links

Search

pnote search "query"              # Full-text search (default limit 20)
pnote search "query" --notes-only # Notes only
pnote search "query" --snippets-only # Snippets only
pnote search "query" --limit 50   # Limit results

PIN protection

Notes can be PIN-protected (encrypted server-side). The PIN is set in the PromptNote web app under Settings.

pnote pin status                   # Check PIN configuration and cache status
pnote pin list                     # List protected notes (metadata only)

# Access protected notes
PNOTE_PIN=1234 pnote notes --protected
PNOTE_PIN=1234 pnote notes get <protected-note-id>
echo "1234" | pnote notes get <id> --pin-stdin

PIN resolution order: -p flag → --pin-stdin → PNOTE_PIN env var (recommended for automation) → 5-min session cache. The interactive prompt is not part of the chain: on a terminal the CLI asks for the PIN only when a command actually reaches a protected note (hidden input, one * per keystroke, 3 attempts) and caches it for 5 minutes. With no terminal attached it never prompts — the command exits with code 5 instead of hanging or pretending the note is empty.

Agent skills sync

Sync agent skill files between PromptNote cloud and your local agent directories. Skills are stored as notes (note_type="skill") with titles like skill-name/filename.md.

pnote skills                          # List skills in cloud
pnote skills pull                     # Pull all globally (~/.agents/skills/ + symlinks)
pnote skills pull <name>              # Pull a specific skill globally
pnote skills pull --project           # Pull project-level (.agents/skills/ + symlinks)
pnote skills pull --dry-run           # Preview without writing files
pnote skills pull --force             # Overwrite conflicts (originals backed up)
pnote skills push <dir>               # Upload local skill directory to cloud
pnote skills push <dir> --name <name>  # Override the skill name
pnote skills push <name> --file <path> # Push a single file
pnote skills diff                     # Compare local files with the cloud
pnote skills scan                     # Read-only inventory of local skills
pnote skills scan --usage             # Include 30-day usage stats
pnote skills scan --path <dir>        # Deep-scan a directory (depth 8)

Skills are written to .agents/skills/<name>/ (canonical) and symlinked into .claude/skills/ (always), plus .windsurf/skills/, .augment/skills/, and .agent/skills/ when those agents are installed. A pull never deletes a real directory or overwrites a locally modified file — it reports a conflict and skips. scan is read-only and covers only the global agent skill directories, project roots derived from agent session records, and the current directory; a repository cloned but never opened in an agent needs --path <dir>.

CLI maintenance

pnote update     # Check npm for a newer version and install it
pnote schema     # Print the full command schema as JSON (for AI agents)

Workflow examples

Pipe search results through jq to extract titles:

pnote search "system prompt" --json | jq '.[].title'

Create a note from a file:

cat my-prompt.txt | pnote notes snippet add <note-id>

Back up all notes as JSON:

pnote notes --json > my-notes-backup.json

Global options

Option	Description
--json	Output as JSON (machine-readable)
--no-color	Disable colors
--plain	Plain text output (no formatting)
-p, --pin <pin>	PIN for accessing protected notes
--pin-stdin	Read PIN from stdin (first line)
-h, --help	Show help
-V, --version	Show version

Environment variables

Variable	Description
PNOTE_TOKEN	API token (overrides stored credentials)
PNOTE_PIN	PIN for accessing protected notes (recommended for automation)
PROMPTNOTE_PIN	Alias for PNOTE_PIN
PNOTE_PIN_CACHE_DIR	Override the PIN session-cache directory
NO_COLOR	Disable colors (standard convention)

Unix conventions

pnote follows Unix philosophy:

• stdout for data, stderr for status messages
• Exit codes: 0 success, 1 general error, 2 auth error, 3 not found, 4 network error, 5 PIN required (the note is protected and stayed locked — it exists, its content is unknown)
• Supports piping: pnote search "x" --json | jq '.[] | .title'
• --json for programmatic consumption

Configuration

Credentials stored in ~/.config/pnote/credentials.json (XDG-compliant).