keep-markdown

CLI for keep.md — search and retrieve saved web content as Markdown.

Setup

1. Sign up for an account at https://keep.md
2. Create an API token at https://keep.md/dashboard
3. Save your token:

npm i -g keep-markdown
keep key <your-token>

Alternatively set the KEEP_API_KEY environment variable.

Usage

keep list --since 7d
keep list --tag agent-tooling --collection x-articles
keep search "react hooks"
keep search "agents" --tag agent-tooling --collection x-articles
keep save https://example.com/article
keep update <id> --processed
keep update <id> --collection x-articles
keep update <id> --collections x-articles,reading-list
keep tags list
keep collections list
keep collections add "X Articles"
keep changes --updated-since 24h --tag agent-tooling
keep changes --cursor <nextCursor> --tag agent-tooling
keep sync ./items.json
keep feed --since 7d
keep feed --tag agent-tooling
keep processed <id1> <id2>
keep get <id>
keep highlights <item-id>
keep highlight <highlight-id>
keep content <id>
keep whoami
keep sources list
keep sources add rss https://example.com/feed.xml
keep webhooks list
keep webhooks add https://example.com/keep-webhook --name "Research sync" --tag research
keep webhooks test <id>
keep stats

Default text output for list, search, and feed is: <id>\t<url>\t<title>

Use --json for structured output. Add --content --json on list or search to include both the structured content object and the rendered contentMarkdown. keep get <id> returns the full item JSON, including saved highlights and summaryMarkdown when an AI summary has been generated (paid plans).

keep highlights <item-id> lists highlights attached to an item. Default text output is <highlightId>\t<itemId>\t<text>. Use --json for the full response. keep highlight <highlight-id> returns one highlight as JSON.

keep content <id> returns the item's markdown with a ## Summary section at the top when a summary is available, followed by the full article body.

Tag and collection filters accept slugs or names. Slugs use lowercase words joined by hyphens, like x-articles or agent-tooling.

Delta sync

Use keep changes when an integration needs to fetch only item changes since its last cursor.

keep changes --updated-since 24h --tag agent-tooling
keep changes --cursor <nextCursor> --tag agent-tooling
keep changes --updated-since 7d --collection x-articles --json

The command returns JSON with events, nextCursor, and hasMore. Store the nextCursor value and pass it to the next run.

Tags and collections

keep tags list
keep collections list
keep collections add "X Articles"
keep list --tag agent-tooling
keep search "agents" --collection x-articles
keep update <id> --collection x-articles
keep update <id> --collections x-articles,reading-list
keep update <id> --clear-collections

Save and sync

Save one URL with server-side extraction:

keep save https://example.com/article

Bulk sync items from a JSON file:

keep sync ./items.json

The sync file can be either an array of items or an object with an items array.

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

Webhooks

Create signed webhook endpoints for item changes:

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 <id>
keep webhooks rotate-secret <id>
keep webhooks remove <id>

Default webhooks list output is <id>\t<status>\t<url>\t<name>\t<events>\t<scope>. Use --json for the full response. webhooks add and webhooks rotate-secret print the signing secret once, so store it when the command returns.

Run keep help for the full list of commands and options.