Use Keep from your terminal
The Keep CLI lets you save, list, search, and retrieve your saved items from the terminal. Useful for piping markdown content into scripts, agents, or other tools.
Install
npm i -g keep-markdown
Setup
Sign up at Keep , create a personal API key on the settings, then save it:
keep key YOUR_API_KEY
Your key is stored in ~/.config/keep/config.json. You can also pass it inline with --key or set the KEEP_API_KEY environment variable.
You can use a read-only scoped key the same way. A scoped key only sees items inside its tag or collection, and commands that write or delete will be rejected. Create personal and scoped keys from your settings.
keep save
Save one URL with server-side extraction.
keep save https://example.com/article
keep sync
Bulk sync items from a JSON file.
keep sync ./items.json
The file can be either an array of item objects or an object with an items array.
keep list
List your saved items. Archived items are excluded by default.
keep list
a1b2c3 https://example.com/article Example Article d4e5f6 https://blog.dev/post Some Blog Post
Filter by time, status, tags, or collection:
keep list --since 7d --status stashed,flagged --tag agent-tooling --collection x-articles --limit 20
Add --content to include the extracted markdown in the JSON output as both content and contentMarkdown. Add --json for raw JSON.
keep search
Search your items by title, URL, notes, tags, and semantic similarity. Add --tag or --collection to keep the search inside a specific filter.
keep search "react hooks" keep search "agents" --collection x-articles --tag agent-tooling
keep get
Get full metadata for a single item.
keep get a1b2c3
Returns the item JSON, including content, contentMarkdown, and saved highlights when available.
keep highlights
List highlights attached to an item.
keep highlights a1b2c3 keep highlights a1b2c3 --json
Default text output is <highlightId>\t<itemId>\t<text>.
keep highlight
Get one highlight by ID.
keep highlight hl_123
Returns the highlight JSON.
keep update
Update an item without leaving the terminal. Tags stay as names. Collections accept ids, names, or slugs.
keep update a1b2c3 --title "Better title" --tags ai,reading keep update a1b2c3 --collection x-articles keep update a1b2c3 --collections x-articles,reading-list keep update a1b2c3 --clear-collections keep update a1b2c3 --processed keep update a1b2c3 --unarchive
keep tags
List tags with both display names and slugs.
keep tags list
keep collections
List collections or create one from the terminal.
keep collections list keep collections add "X Articles"
keep content
Print the extracted markdown for an item. Useful for piping into other tools. This is a shortcut for reading content directly without the rest of the item JSON.
keep content a1b2c3
# Example Article The full extracted markdown content of the page...
keep archive
Archive an item to hide it from your default list. Shortcut for keep update --archive.
keep archive a1b2c3
keep whoami
Display your account info -- plan, limits, and usage.
keep whoami keep me
keep stats
Usage statistics for a date range.
keep stats --since 30d
keep feed
List unprocessed items with their full content. Designed for AI agents that consume your saved items as context. Supports the same --tag and --collection filters as keep list.
keep feed --limit 10 keep feed --collection x-articles --tag agent-tooling
keep changes
Poll for item change events for delta sync. Returns JSON events in order with a cursor so you can sync incrementally instead of re-listing everything. See Webhooks for a push alternative.
keep changes --updated-since 7d keep changes --cursor NEXT_CURSOR keep changes --collection x-articles --tag agent-tooling --content
Options: --cursor, --updated-since, --tag, --collection, --limit, and --content. Save the nextCursor from each response and pass it back as --cursor on the next run to fetch only what changed since.
keep processed
Mark one or more items as processed so they leave the feed.
keep processed a1b2c3 d4e5f6
keep sources
Manage RSS, YouTube, X article, and email inbox sources.
keep sources list keep sources add rss https://example.com/feed.xml keep sources add youtube @fireship_dev keep sources add x levelsio keep sources add email keep sources remove src_123
keep webhooks
Manage signed webhook endpoints that send item changes to your own app. See Webhooks for the payload, signature, and delivery details.
keep webhooks list keep webhooks add https://example.com/keep-webhook --name "Research sync" keep webhooks add https://example.com/keep-webhook --tag research keep webhooks add https://example.com/keep-webhook --events item.created,item.tagged keep webhooks test <webhook-id> keep webhooks rotate-secret <webhook-id> keep webhooks remove <webhook-id>
webhooks add options: --name, --events (comma-separated event names, default *), --tag (restrict to one tag), and --collection (restrict to one collection id).
Default webhooks list output is <id>\t<status>\t<url>\t<name>\t<events>\t<scope>. Add --json for the full response. webhooks add and webhooks rotate-secret print the signing secret once, so store it when the command returns.
Global options
These flags work with any command:
--json -- output raw JSON instead of formatted text
--key <token> -- use a specific API key for this request
--base <url> -- override the API base URL