clipshelf-cli

# ClipShelf CLI Skill Use the `clipshelf` CLI to interact with the ClipShelf clipboard manager from the terminal. The CLI shares the same SQLite database as the macOS GUI app, so changes are reflected in both. ## Prerequisites The `clipshelf` binary must be available on `$PATH`. Install via Homebrew: ```bash brew tap crossoverJie/homebrew-tap brew install crossoverjie/tap/clipshelf ``` Verify: ```bash clipshelf --help ``` If the binary is not found, inform the user and stop — do not attempt alternative access methods. ## Command Reference ### Read Operations #### Fetch recent items ```bash clipshelf recent [--limit N] [--output json|ndjson|text] ``` - Default limit: 10 - Default output: `json` - Use `--output text` when you only need plain text content - Use `--output ndjson` for streaming / large result sets #### Query by tag or text ```bash clipshelf query [--tag TAG ...] [--match-any-tag] [--text "substring"] [--limit N] [--output json|ndjson|text] ``` - Multiple `--tag` values use AND semantics by default - Add `--match-any-tag` to switch to OR semantics - `--text` performs case-insensitive substring matching #### Get a single item by ID ```bash clipshelf get <uuid> [--output json|ndjson|text] ``` ### Write Operations #### Add a text item ```bash # From argument clipshelf add --text "content" [--tags TAG ...] [--print-id] # From stdin (pipe-friendly) echo "content" | clipshelf add --stdin [--tags TAG ...] [--print-id] ``` - Either `--text` or `--stdin` is required (mutually exclusive) - `--tags` accepts multiple values: `--tags work --tags important` - `--print-id` outputs only the UUID of the created item (useful for scripting) #### Delete an item ```bash clipshelf delete <uuid> ``` ### Tag Management ```bash # List all tags clipshelf tags list [--output json|ndjson|text] # Create a tag clipshelf tags create <name> [--color #808080] ``` ## Output Formats | Format | Flag | Use case | |--------|------|----------| | JSON | `--output json` (default) | Structured data, jq processing. Wrapped in `{"schemaVersion":"1","data":[...]}` | | NDJSON | `--output ndjson` | Streaming, large datasets. One JSON object per line (no envelope) | | Text | `--output text` | Plain content only, one item per line. No metadata | ### JSON envelope structure (default) ```json { "schemaVersion": "1", "data": [ { "id": "uuid-string", "contentType": "text", "textContent": "...", "createdAt": "ISO-8601", "tags": ["tag1"], "isPinned": false } ] } ``` ## Error Handling Errors are written to stderr as structured JSON. Check exit codes: | Exit code | Meaning | |-----------|---------| | 0 | Success | | 2 | Invalid argument or empty stdin | | 3 | Resource not found | | 4 | Access denied | | 5 | Store/database error | | 6 | Conflict (e.g. duplicate tag) | | 10 | Unknown error | Always check the exit code when running CLI commands. On non-zero exit, read stderr for the error message and report it to the user. ## Common Patterns ### Search for specific content ```bash clipshelf query --text "keyword" --limit 20 ``` ### Get all items with a tag ```bash clipshelf query --tag work --limit 100 ``` ### Save output for later processing ```bash clipshelf recent --limit 50 --output ndjson > /tmp/shelf_export.ndjson ``` ### Add multi-line content from a file ```bash cat notes.txt | clipshelf add --stdin --tags notes ``` ### Add an item and capture its ID ```bash ITEM_ID=$(clipshelf add --text "hello" --print-id) echo "Created: $ITEM_ID" ``` ### Combine with jq for filtering ```bash clipshelf recent --limit 100 | jq '.data[] | select(.isPinned == true) | .textContent' ``` ## Guidelines 1. **Default to JSON output** — it provides the most context (IDs, tags, timestamps). Use `--output text` only when the user explicitly wants plain content. 2. **Respect limits** — always set `--limit` to a reasonable value. Don't fetch thousands of items unless the user asks. 3. **Use --print-id when scripting** — if you need the created item's ID for follow-up operations, use `--print-id` instead of parsing full JSON output. 4. **Prefer --stdin for long content** — for multi-line or large text, pipe via stdin rather than passing `--text` with embedded newlines. 5. **Check exit codes** — always verify the command succeeded before acting on the output. 6. **Don't modify data without confirmation** — before deleting items or creating tags, confirm with the user what will be changed. 7. **Same database as the GUI app** — items added/deleted via CLI are immediately visible in the macOS app and vice versa.