Use Keep from your terminal
The Keep CLI lets you search notes and saved items together from the terminal. You can also create and update Markdown notes or pipe saved content into another tool.
Install
npm i -g keep-markdown keep --version
Setup
Sign up at Keep , create a personal API key on the settings, then save it:
keep key YOUR_API_KEY keep auth add codex
Your personal key is stored in ~/.config/keep/config.json. keep auth add <client> asks for confirmation and creates a separate named credential for an
AI tool or other client. Keep selects Codex and Claude credentials
automatically on later commands, and the client name appears in Note history.
Check or remove connections with:
keep auth status keep auth list keep auth remove codex
Connected clients can read and write library content, but cannot create more
credentials. Revoking one does not affect your personal key or other clients.
You can also pass a key inline with --key or set KEEP_API_KEY for a specific
request.
In an interactive terminal, setup also offers to install the Keep skill so compatible AI tools can search and save your context. You can manage it later:
keep skill install keep skill status keep skill update
Keep checks the installed skill at most once per day. Interactive commands can offer to update after they finish. Piped and --json commands print any update notice to stderr, leaving stdout unchanged for AI tools and scripts. Set KEEP_NO_SKILL_UPDATE_CHECK=1 to disable these checks.
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 context
Search notes and saved items together. Keep detects the current Git remote and repo-relative directory so relevant handoffs can rank higher.
keep context "what did we decide about note sync" keep context "authentication handoff" --limit 10
Add --content when you need the returned note body or item summary. Search stays shallow by default.
keep notes
Search and read Markdown notes:
keep notes search "OAuth verification" keep notes get note_123 keep notes get note_123 --sources --history keep notes get note_123 --sources --content --content-bytes 80000 keep notes history note_123
Expanded reads return JSON. --sources adds attached item summaries and
highlights, --history adds recent revision summaries, and --content adds
bounded full item content. Lower the response limits with --source-limit,
--history-limit, or --content-bytes.
Create or update a note from a local Markdown file:
keep notes create --title "OAuth verification" --body-file note.md
keep notes create --title "OAuth verification" --body-file note.md --tags oauth,seo --properties-json '{"kind":"handoff","state":"open"}'
keep notes append note_123 --body-file result.md --revision 2
keep notes update note_123 --body-file replacement.md --revision 3
keep notes update note_123 --revision 4 --properties-json '{"state":"closed"}'
Updates use the current revision number. If another person or tool changes the note first, read it again and retry with the newer revision.
When you create a note inside a Git repository, Keep records the remote project
and repo-relative path automatically. Use --project, --path, --tags, or
--properties-json to add or override metadata, and --no-context to skip Git
detection. Metadata-only updates merge with the Note's current properties.
Attach saved items or highlights as supporting context:
keep notes attach note_123 item_456 --relation evidence keep notes attach note_123 item_456 --highlight-id highlight_789 keep notes detach note_123 nlink_456
Successful note writes print the note ID, revision, title, and its authenticated Keep link. Add --json to receive the link as webUrl.
The attach response includes the link id used by notes detach. Relations can
be source, evidence, example, inspiration, or annotation.
Export every current and archived Note as portable Markdown:
keep notes export keep notes export --output ./keep-notes.zip
The ZIP contains one Markdown file per Note. Frontmatter includes the stable
Note ID, revision, timestamps, archive state when present, and custom
properties. Without --output, Keep writes a dated ZIP in the current folder.
Optional session summaries
Ask the current AI to prepare one detailed session summary with:
keep session prompt keep session prompt --json
The command returns a prompt and write contract. It does not save anything by itself. The summary covers material decisions and reasoning, concrete work, files, URLs, checks, failures, remaining work, and terms that will help you find it later.
To save one summary automatically when a Claude Code or Codex 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
Installation asks for confirmation because each non-empty completed session
uses one additional request from that model client. Existing hooks are
preserved, and removal deletes only Keep's own SessionEnd entry.
Session exit queues the summary locally. Empty sessions are skipped, and a stable session ID limits each completed session to one Note even if the hook runs twice or a failed job is retried. Raw transcripts are not uploaded to Keep; only the generated Markdown summary is saved.
Use keep session status to see pending, saved, skipped, or failed jobs. After
fixing a failed authentication or model CLI check, run keep session retry <job-id>.
keep get
Get full metadata for a single item.
keep get a1b2c3
Returns the Item JSON, including content, contentMarkdown, saved highlights, and connected Notes when available to the current API key.
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 tools and scripts that use 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:
-v, --version -- print the installed CLI version
--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