keep

CLI for Keep. Save links as Markdown, search Notes and saved Items, and read or update them from a terminal or AI agent.

Setup

1. Sign up for an account at https://app.keep.md/signup
2. Install the CLI and sign in through your browser:

npm i -g keep
keep --version
keep login
keep auth status

keep login shows a short code, opens Keep in your browser, and waits while you approve it. Approving gives this client its own named, revocable library credential. No API key is involved.

If an AI agent is setting up Keep for you, it should run keep login itself. You only need to sign in, check the code, and approve access in the browser.

For an MCP-first setup use the MCP guide. The browser extension guide covers Chrome, Arc, Brave, and Firefox.

Use the exact lowercase name for the current client:

| Current client | Login name | | --- | --- | | ChatGPT | chatgpt | | Claude Code | claude-code | | Claude Desktop | claude-desktop | | Codex | codex | | Cursor | cursor | | OpenCode | opencode | | Pi | pi |

Name the client when you want a specific label, and use --no-browser on a machine that cannot open one:

keep login codex
keep login --no-browser

If you installed the previous package name, replace it without deleting your Keep config or credentials:

npm uninstall -g keep-markdown
npm i -g keep

Codex, Claude Code, and Cursor are detected during login and selected automatically on later commands, so Note history shows which client made each change. Use keep auth status, keep auth list, and keep auth remove <client> to inspect or disconnect them.

Older claude connections and optional session hooks continue to work as Claude Code. Claude Desktop always uses its separate claude-desktop connection.

API keys remain available for scripts and integrations that need one. Create one at https://app.keep.md/settings/connections#api, save it with keep key <your-token>, or set KEEP_API_KEY for a specific request. Do not paste a personal API key into an AI conversation or prompt.

When setup runs in an interactive terminal, Keep offers to install the keep skill for compatible AI tools. You can install or check it later:

keep skill install
keep skill install --agent codex --global
keep skill install --copy --yes
keep skill status
keep auth status
keep skill update

Without the Keep CLI, install the same skill from Keep's public discovery index:

npx skills add https://keep.md --skill keep

Keep checks installed skill instructions at most once per day. Interactive commands can update after they finish. Piped and --json commands only write an update notice to stderr, so stdout stays safe for AI tools and scripts. Set KEEP_NO_SKILL_UPDATE_CHECK=1 to disable automatic checks.

Usage

keep list --since 7d
keep list --tag agent-tooling --collection x-articles
keep search "react hooks"
keep search "what did we decide about note sync?"
keep search "release decision" --types note --mode lexical
keep items search "agents" --tag agent-tooling --collection x-articles
keep save https://suganthan.com/blog/webmcp-implementation-guide/
keep extract <item-id>
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> --media
keep get <id> --find "payment failure"
keep get <id> --lines 40:90
keep get <id> --full
keep highlights <item-id> --limit 25
keep media <item-id> --limit 20
keep highlight <highlight-id>
keep content <id>
keep notes search "writing idea"
keep notes get <note-id>
keep notes get <note-id> --full
keep notes get <note-id> --overview
keep notes get <note-id> --find "authentication" --revision 4
keep notes get <note-id> --lines 20:80 --revision 4
keep notes create --title "Article idea" --body-file ./idea.md
keep notes create --title "Article idea" --body-file ./idea.md --tags writing,ideas
keep notes append <note-id> --body-file ./progress.md
keep notes update <note-id> --revision 2 --state closed
keep notes history <note-id>
keep notes get <note-id> --sources --history
keep notes attach <note-id> <item-id> --relation evidence
keep notes detach <note-id> <link-id>
keep notes export --output ./keep-notes.zip
keep skill status
keep whoami
keep sources list
keep sources add rss https://simonwillison.net/atom/everything/
keep sources update <id> --summaries off --full-content on
keep webhooks list
keep webhooks add "$KEEP_WEBHOOK_URL" --name "Research sync" --tag research
keep webhooks test <id>
keep stats

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

Use --json for structured output. Add --content --json on list or items search to include both the structured content object and the rendered contentMarkdown. keep get <id> returns a compact overview with metadata, content statistics, and headings. Use --find to get matching windows, --lines for an exact slice, and --full only when the whole captured document is needed. --content remains an alias for --full.

Add --media to include one bounded media page with the read, or use keep media <item-id> --limit 20 --offset 0 to page image references separately. Remote captures return their original HTTPS URLs; direct image uploads return authenticated Keep URLs. keep highlights <item-id> similarly returns a bounded page and accepts --limit and --offset. keep highlight <highlight-id> returns one highlight as JSON.

keep content <id> returns the item's markdown. Source frontmatter remains the first block when present, followed by a ## Summary section when a summary is available, then the full article body.

Notes

Notes are editable Markdown documents that you and the AI tools you use can share through Keep. Create one from a local file, retrieve it as Markdown, or append new work without overwriting another writer's changes.

Feed Items remain captured source material. When an Item prompts a useful thought, create or update a Note and attach the Item as evidence.

keep notes search "writing idea"
keep notes get <note-id>
keep notes get <note-id> --full
keep notes get <note-id> --overview
keep notes get <note-id> --find "authentication" --revision 4
keep notes get <note-id> --lines 20:80 --revision 4
keep notes create --title "Article idea" --body-file ./idea.md
keep notes create --title "Article idea" --body-file ./idea.md --tags writing,ideas
keep notes update <note-id> --body-file ./idea.md --revision 1
keep notes update <note-id> --revision 3 --clear-tags --clear-project
keep notes append <note-id> --body-file ./progress.md
keep notes history <note-id>
keep notes get <note-id> --sources --history --content
keep notes attach <note-id> <item-id> --relation evidence
keep notes attach <note-id> <item-id> --highlight-id <highlight-id>
keep notes detach <note-id> <link-id>
keep notes export --output ./keep-notes.zip

Successful note writes print the bare note ID, revision, title, and its authenticated Keep link. JSON receipts contain compact Note and revision coordinates plus metadataDiff; they never echo the Note body. Read the returned revision only when verification or more context is needed. Commands also accept older IDs beginning with note_.

The revision number prevents stale replacements. notes update requires the current revision returned by create, get, or history. notes append uses the latest revision and safely retries a concurrent append. Pass --revision to append only when a stale revision should fail instead. Add --json when another tool or AI needs structured data.

New Notes do not get Git metadata by default. Add --project or --path when that metadata is useful. Use --context to detect both values from the current Git repository. Add --tags, --kind, or --state as needed, and use --properties-json only for custom metadata. The older --no-context flag remains accepted for compatibility.

Metadata-only updates do not require --body-file. Fields you omit stay unchanged. Use --clear-tags, --clear-project, --clear-kind, or --clear-state when you mean to remove a first-class field. Custom properties are merged separately. Use --clear-properties only when all custom metadata should be removed. Append keeps the title and all metadata unchanged. It also keeps the same request ID while resolving a concurrent append, so a retry does not duplicate the Markdown. Use notes update when the title or metadata needs to change.

The CLI rejects unknown flags and flags used with the wrong command before it makes an API request. A misspelled metadata flag cannot silently drop part of an update.

Add --sources to notes get to return the Note with attached Item summaries and highlights. Add --history for recent revision summaries or --content for bounded full Item content. Expanded reads return JSON. Use --source-limit, --history-limit, and --content-bytes to lower the response limits.

notes get returns an overview by default. It includes the Note revision, token and line counts, and a heading outline without returning the full body. Reuse that revision with --find <text> to locate matching lines, then --lines <start:end> to fetch only the required Markdown. Exact slices are limited to 200 lines and 32 KB. Find results return at most 200 lines and 16 KB in total. These progressive reads always return structured JSON so the selected revision and line numbers remain explicit. Use --full only when the bounded reads cannot answer the question. Reads do not use Note credits; creating or importing a new Note does. Editing an existing Note does not use another credit.

Attach an Item as source, evidence, example, inspiration, or annotation. The attach response includes the link ID needed by notes detach.

keep notes export downloads every current and archived Note as a ZIP with one portable Markdown file per Note. Each file includes Keep-owned identity and revision fields plus your custom properties. Use --output <path> to choose the destination; otherwise Keep uses a dated filename in the current folder.

Search

keep search searches Notes and saved Items together across your library.

keep search "implement note sync"
keep search "authentication decision" --types note
keep search "release decision" --mode lexical
keep search "search design" --content --content-bytes 80000

Results stay shallow by default, with snippets capped at 600 UTF-8 bytes. Note matches include the revision and a relevant line range when available. Pass those coordinates directly to notes get --lines when the range is already useful. Use --mode lexical, --mode semantic, or --mode hybrid to choose matching behaviour. Use --content when you need the matched Markdown, or --json for the complete ranked response.

Use the resource-specific commands when you only want one side of the library:

keep notes search "article idea"
keep items search "agents" --collection x-articles

keep notes search uses the same bounded search response as keep search; it does not download every matching Note body. Pass --project <git-url> --exact-project to restrict a search to one repository, use --context to detect the current Git Project for this search, or add --content only when the next step needs the matched text.

keep context remains an advanced compatibility command. It detects the current Git Project and path. keep context brief --json returns a maximum of 20 recent Note titles and retrieval cues for that Project.

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

Advanced Project and session compatibility

Normal setup does not install session hooks or add Git Project metadata to new Notes. Existing hooks and Project data continue to work. Use these commands only when you want that coding-session workflow.

Ask the current AI to create a detailed one-Note summary with Keep's versioned prompt and write contract:

keep session prompt
keep session prompt --json

The prompt itself does not write anything. It tells the current AI to capture decisions and reasoning, work completed, files, URLs, verification, failures, remaining work, and useful retrieval terms in exactly one Note.

Claude Code, Codex, and Pi can load recent project Notes at session start and save a summary automatically when a session ends:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
keep login claude-code
keep login codex
keep login pi
keep hooks install all
keep hooks status
keep hooks doctor
keep session status
keep session retry <job-id>
keep hooks remove all

At session start, Keep returns at most 20 matching Note titles and retrieval cues. It does not load Note bodies, make a model request, or write anything. The lookup fails open, so it never blocks a session when Keep is unavailable.

Installation is opt-in and explains that each non-empty completed session uses one additional Claude Code, Codex, or Pi model request at session end. It preserves unrelated hooks, backs up an existing configuration before changing it, and removal deletes only Keep's managed hook entries or integration file. Authenticate each model CLI and verify that it can answer a prompt first; keep hooks doctor checks the executable and version, not provider access.

The hook queues work locally so session exit is not delayed. The model client resumes its completed session only to return one Markdown summary; it cannot write to Keep itself. The CLI checks the output and makes at most one Note write with a stable session request ID, so a duplicate event or retry does not create another Note.

all installs the full start and end lifecycle for Claude Code, Codex, and Pi. Cursor can install the current start-only preview, while OpenCode gets an explicit handoff command:

keep login cursor
keep hooks install cursor

npm install -g opencode-ai
keep login opencode
keep hooks install opencode

Raw transcripts are never uploaded to Keep. Only the generated summary is saved. Empty sessions are skipped. Failed jobs stay local and appear in keep session status; retry one after fixing the reported auth or model CLI problem with keep session retry <job-id>.

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 items 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://suganthan.com/blog/webmcp-implementation-guide/

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 list --include-settings
keep sources list --include-sensitive
keep sources add rss https://simonwillison.net/atom/everything/
keep sources add youtube @fireship_dev
keep sources add x levelsio
keep sources add email
keep sources update <id> --summaries off --full-content on
keep sources update <id> --name "Simon Willison" --tags ai,engineering
keep sources remove <id>

Creation supports names, default tags, smart tag rules, backfill controls, polling intervals, full-content control, and summary control. sources update can change the name, tags, full-content setting, and summary setting.

sources list returns a compact status manifest without configuration, tag rules, or internal cursors. Add --include-settings for redacted configuration and rules. Use --include-sensitive only while debugging a source you control. Its output may contain credentials, so do not paste it into a chat, issue, log, or Note.

Reddit saved-feed links from old Reddit can be added as RSS sources in either the root or user-scoped URL form. Keep fetches the Reddit post instead of using the feed's small link card when full-content capture is on. Turn on summaries for the source when you want an AI summary of that fetched content. YouTube sources retry temporary feed lookup failures after refreshing the channel details.

Webhooks

Create signed webhook endpoints for item changes:

keep webhooks list
keep webhooks add "$KEEP_WEBHOOK_URL" --name "Research sync"
keep webhooks add "$KEEP_WEBHOOK_URL" --tag research
keep webhooks add "$KEEP_WEBHOOK_URL" --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.