CLI

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.

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.

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 and contentMarkdown when available.

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 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

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