Skip to content
Capd
Esc
↑↓navigate↵open⌘Jpreview
On this page

CLI

Capture, search, manage, and export your Capd library from the terminal.

The bundled capd command works with the same local library as the Capd app. It is useful for quick terminal capture, bulk imports, shell scripts, backups, and AI-assistant integrations.

Homebrew adds capd to your PATH. Direct installations keep it at /Applications/capd.app/Contents/MacOS/capd.

Capture

capd add https://example.com/article      # save a link and queue its page content
capd add https://example.com --no-fetch   # save the link without fetching the page
capd add "Remember this" --note "Why"     # save text with a note
capd add https://example.com --title "…"  # provide a title
pbpaste | capd add -                      # capture standard input
capd add https://example.com --wait       # wait for enrichment to finish

When standard input contains only URLs, each non-empty line becomes a separate capture. Otherwise, the complete input becomes one text capture.

--wait times out after 60 seconds by default. Use --timeout <seconds> to change it. CLI captures use the same duplicate detection as the app.

Search and list

capd search swift concurrency --site swift.org --since 2026-01-01
capd search 'error handling until:2026-06-30'
capd list --limit 20

search and list accept --limit and --format plain|tsv|json. The filter syntax is shared with the app.

Manage captures

capd rm 12 14       # delete captures by ID
capd refetch        # retry all failed or thin page extractions
capd refetch 12     # retry a specific capture

IDs appear in capd list and capd search output.

Import

capd import pinboard pinboard_export.json   # the JSON backup from pinboard.in

Download the export from pinboard.in under Settings → Backup → JSON. Bookmarks keep their titles, notes, tags, and original timestamps; unread bookmarks gain a toread tag. Links already in the library merge instead of duplicating, so re-running an import is safe.

Imported tags are stored as-is and are never rewritten by automatic tagging. Imported links skip page fetching; run capd refetch <id> to fetch a page for search later. The same import is available in the app from the menu bar icon.

Export

capd export                    # lossless JSON with every stored field
capd export --format markdown  # readable links, notes, and selections

The JSON export is the complete portable backup format. Copy the entire storage folder when captured image files must be included as well.

Connect an AI assistant

capd mcp

capd mcp serves four read-only tools over the Model Context Protocol:

  • search_captures uses Capd’s full-text search and filters.
  • get_capture returns one capture with its extracted page text.
  • list_recent returns the latest captures.
  • ask_cap answers across the library with numbered capture citations using Apple’s on-device model.

Register it with Claude Code:

claude mcp add capd -- capd mcp

Or add it to Claude Desktop’s claude_desktop_config.json:

{
  "mcpServers": {
    "capd": { "command": "capd", "args": ["mcp"] }
  }
}

Capd’s MCP server cannot add, edit, or delete captures. It communicates over standard input and output; review the privacy policy of the assistant receiving the results to understand whether that assistant sends them elsewhere.

Use Raycast

The Capd extension for Raycast is another client for the same local library. It adds two commands:

  • Capd: Search searches your captures and accepts the same site:, tag:, after:, and before: filters as the app. An empty search bar lists your most recent captures.
  • Capd: Capture saves a link or text from a command argument, the current selection, or the clipboard. Set it as a Raycast fallback command to capture whatever you type into root search.

The extension runs the bundled capd command and nothing else, so captures and searches stay on your Mac. It locates capd inside the installed capd.app, which means a direct .dmg install works without adding anything to your PATH.

Check health

capd status   # queue, capture, storage, and background-helper status
capd doctor   # integrity checks, repairs, and permission status

capd doctor can rebuild the search index, remove orphaned image files, and repair the background helper. Use capd doctor --uninstall-agent to remove the helper or --skip-agent to check only the library.

Conventions

  • Data goes to standard output; diagnostics go to standard error.
  • Exit codes are 0 for success, 1 for no results, 2 for invalid usage, 3 when the store is unavailable, and 4 when the helper is not running.
  • CAPD_DIR overrides the default storage root.
  • JSON output is stable for scripts. Existing fields are not renamed, retyped, or removed, but new fields may be added. Consumers should ignore unknown keys.

Was this page helpful?