keep

CLI for Keep, your personal context library for thoughts, ideas, notes, saved content, and the things you learn.

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
keep --version
keep key <your-token>
keep auth add codex

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

keep auth add <client> asks for confirmation, then gives that AI tool or other client its own named, revocable library credential. Codex and Claude are 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.

The personal key remains the bootstrap credential. Rolling it does not revoke connected clients. Alternatively, scripts can set the KEEP_API_KEY environment variable for a specific request.

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 status
keep auth status
keep skill update

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 items 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> --media
keep highlights <item-id>
keep highlight <highlight-id>
keep content <id>
keep notes search "handoff"
keep notes get <note-id>
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 "Project handoff" --body-file ./handoff.md
keep notes create --title "Project handoff" --body-file ./handoff.md --tags handoff,keep
keep notes append <note-id> --body-file ./progress.md --revision 1
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 hooks status
keep session status
keep skill status
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, 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 the full Item JSON, including saved highlights, connected Notes when available to the current API key, and summaryMarkdown when an AI summary has been generated (paid plans). Add --media when an AI or another client needs the ordered image references in content.media. Remote captures return their original HTTPS URLs; direct image uploads return authenticated Keep URLs.

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. 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 "open handoff"
keep notes get <note-id>
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 "Project handoff" --body-file ./handoff.md
keep notes create --title "Project handoff" --body-file ./handoff.md --tags handoff,keep --kind handoff --state open
keep notes update <note-id> --body-file ./handoff.md --revision 1
keep notes update <note-id> --revision 2 --state closed
keep notes append <note-id> --body-file ./progress.md --revision 2
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 note ID, revision, title, and its authenticated Keep link. JSON output includes the same link as webUrl.

The revision number prevents stale updates. Use the current revision returned by create, get, or history. Add --json when another tool or AI needs structured data.

When creating a Note inside a Git repository, the CLI attaches the repository to its Project and stores the repo-relative directory as custom path frontmatter. Override the Project with --project, add --tags, --kind, or --state, and use --properties-json only for custom metadata. Use --no-context to skip Git metadata.

Metadata-only updates do not require --body-file. Custom properties are merged so unrelated fields are preserved. Use --clear-properties only when custom metadata should be removed. Append keeps all existing metadata; use notes update when metadata also needs to change.

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.

For a large Note, start with --overview. It returns 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 find results return at most 200 lines of context in total. These progressive reads always return structured JSON so the selected revision and line numbers remain explicit.

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. In a Git repository it automatically includes the origin remote and your repo-relative working path, so current handoffs and decisions rank ahead of unrelated matches.

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

Results stay shallow by default. Use --content when you need the matched Markdown, or --json for the complete ranked response. keep context remains a compatibility alias.

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

keep notes search "open handoff"
keep items search "agents" --collection x-articles

keep context brief --json returns a maximum of 20 recent Note titles and retrieval cues for the current Git project. It is an index for agents, not a download of the Note bodies.

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

Optional session summaries

You can 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 and Codex can load recent project Notes at session start and save a summary automatically when a session ends:

keep auth add claude
keep auth add codex
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 or Codex model request at session end. It preserves unrelated hooks, backs up an existing configuration before changing it, and removal deletes only Keep's own SessionStart and SessionEnd entries.

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.

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

Reddit saved-feed links from old Reddit can be added as RSS sources in either the root or user-scoped URL form. 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 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.