SaveIt CLI

The saveit npm package ships with a saveit executable. No clone, no build - just npx.

npx saveit auth set <your-api-key>
npx saveit bookmarks list --tags dev,ai --limit 10 --json

Install

You don't have to. npx saveit ... downloads on demand. If you'd rather have a permanent binary on your PATH:

npm install -g saveit
# or
pnpm add -g saveit

Then drop the npx prefix from every example below.

Authenticate

Create an API key at saveit.now/account/keys, then save it:

npx saveit auth set <your-saveit-api-key>
npx saveit auth test

The token is stored at ~/.config/tokens/saveit.txt with chmod 600. The CLI also reads SAVEIT_API_KEY from the environment - useful for CI:

export SAVEIT_API_KEY=<your-saveit-api-key>
npx saveit bookmarks list --json

Command	Description
saveit auth set <token>	Save the token (chmod 600)
saveit auth show	Show masked token
saveit auth show --raw	Show full token (for piping)
saveit auth test	Verify token works
saveit auth remove	Delete the saved token

Bookmarks

# List + search
saveit bookmarks list
saveit bookmarks list --query "next.js" --limit 5
saveit bookmarks list --tags design,ux --json
saveit bookmarks list --types ARTICLE,YOUTUBE --special UNREAD
saveit bookmarks list --cursor <cursor> --limit 50

# Create
saveit bookmarks create --url "https://example.com"
saveit bookmarks create --url "https://example.com" --metadata '{"source":"slack"}'

# Random unopened bookmark (also marks it as opened)
saveit bookmarks random

# Delete
saveit bookmarks delete bm_1234567890

Flag	Commands	Description
--query <q>	list	Full-text search
--tags <a,b>	list	Comma-separated tag filter
--types <t1,t2>	list	VIDEO, ARTICLE, PAGE, IMAGE, YOUTUBE, TWEET, PDF, PRODUCT
--special <s>	list	READ, UNREAD, or STAR
--limit <n>	list	Page size, 1-100, default 20
--cursor <c>	list	Pagination cursor (from previous nextCursor)
--fields <a,b>	list	Columns to render in text/csv output
--url <url>	create	URL to save (required)
--transcript <t>	create	Optional transcript text
--metadata <json>	create	Optional JSON object

Tags

saveit tags list
saveit tags list --limit 100 --json
saveit tags list --cursor <cursor>

Global flags

Available on every command:

Flag	Description
--json	Output as JSON (recommended for scripts)
--format <text|json|csv|yaml>	Output format (default: text)
--verbose	Print debug info to stderr
--no-color	Disable ANSI colors
--no-header	Strip headers from text/csv output

Scripting

Pipe to jq, hand to xargs, etc:

# Print every URL in your unread queue (NUL-delimited, safe with weird URLs)
saveit bookmarks list --special UNREAD --limit 100 --json \
  | jq -j '.data[] | .url, ""' \
  | xargs -0 -n1 echo

# Bulk-import URLs from a file (one URL per line, no shell metacharacter expansion)
xargs -a urls.txt -I {} -- saveit bookmarks create --url "{}" --json

# Save a Markdown summary of your tags
saveit tags list --json | jq -r '.data[] | "- \(.name) (\(.bookmarkCount))"'

Heads up: Bookmark url/title/summary/tag names are untrusted remote content (whatever site you saved). Don't feed them straight into bash -c, eval, xargs without -0/-I, or any tool that interprets shell or formula syntax. CSV output is auto-defanged for =/+/-/@ formula injection, but piping into other commands is your responsibility.

Exit code is non-zero on any API or network error.

Next steps

• SDK guide - same operations programmatically
• AI integration prompt - drop into Claude/GPT to give it CLI superpowers
• API reference