keeply-cli

Command-line interface for Keeply — read, save, search, and manage your bookmarks from the terminal.

Designed to work great standalone and as a data source for AI agents and shell scripts.

Requires Keeply Plus. CLI access is a Plus-plan feature.

Installation

Homebrew (macOS and Linux) — recommended

brew tap keeply-link/keeply
brew install keeply

npm (requires Node.js 18+)

npm install -g @keeply-link/cli

From source

git clone https://github.com/keeply-link/keeply-cli
cd keeply-cli
npm install && npm run build
npm link

Setup

keeply login

This opens your browser to authenticate with your Keeply account. Once you approve, your session is saved automatically. Requires a Keeply Plus account.

# Check what's stored
keeply config show

# For CI / non-interactive environments, set an API key directly
keeply config set-key <your-api-key>

Config is stored at ~/.config/keeply-cli/config.json.

Commands

keeply login

Authenticate via browser. Opens app.keeply.tools to complete the OAuth flow, then saves your credentials locally.

keeply login           # Open browser and authenticate
keeply login --force   # Re-authenticate even if already logged in

keeply list · keeply ls

List your bookmarks with optional filters and pagination.

keeply list                          # All bookmarks, 20 per page
keeply list --folder "Reading List"  # Filter by folder name
keeply list --folder <folder-id>     # Filter by folder ID
keeply list --tag typescript         # Filter by tag
keeply list --archived               # Archived bookmarks only
keeply list --page 2                 # Go to page 2
keeply list --limit 50               # 50 results per page
keeply list --limit 0                # No pagination, return all
keeply list --short                  # Compact one-line output
keeply list --json                   # Raw JSON output

Options

| Flag | Description | |------|-------------| | -f, --folder <name\|id> | Filter by folder name or ID | | -t, --tag <name> | Filter by tag name | | -a, --archived | Show archived bookmarks only | | -l, --limit <n> | Results per page (default: 20, 0 = all) | | -p, --page <n> | Page number (default: 1) | | -s, --short | Compact one-line output | | --json | Raw JSON (great for piping) |

keeply search <query>

Search across titles, URLs, descriptions, and notes.

keeply search "rust async"
keeply search "machine learning" --short
keeply search "react hooks" --json

Options

| Flag | Description | |------|-------------| | -s, --short | Compact one-line output | | --json | Raw JSON output |

keeply get <id>

Fetch a single bookmark by its ID.

keeply get cm3x7abc123
keeply get cm3x7abc123 --json

keeply add <url>

Save a new bookmark.

keeply add https://example.com
keeply add https://example.com --title "Example Site"
keeply add https://example.com --folder "Dev"
keeply add https://example.com --tags "web,tools,reference"
keeply add https://example.com --note "Check this out later"
keeply add https://example.com --json  # Returns created bookmark as JSON

Options

| Flag | Description | |------|-------------| | -t, --title <title> | Bookmark title | | -n, --note <note> | Personal note | | -f, --folder <name\|id> | Folder to save into | | --tags <tags> | Comma-separated tag names (must already exist in Keeply) | | --json | Output created bookmark as JSON |

Note: Tags must already exist in your Keeply account. Create new tags in the web app or browser extension.

keeply update <id>

Update an existing bookmark.

keeply update <id> --title "Better title"
keeply update <id> --url https://new-url.com
keeply update <id> --folder "Archive"
keeply update <id> --unfolder           # Move to Unsorted
keeply update <id> --tags "rust,cli"    # Replace all tags
keeply update <id> --archive
keeply update <id> --unarchive
keeply update <id> --json               # Output updated bookmark as JSON

Options

| Flag | Description | |------|-------------| | --url <url> | New URL | | -t, --title <title> | New title | | -n, --note <note> | New note | | -f, --folder <name\|id> | Move to folder | | --unfolder | Remove from folder (move to Unsorted) | | --tags <tags> | Replace all tags (comma-separated names) | | --archive | Mark as archived | | --unarchive | Remove archived status | | --json | Output updated bookmark as JSON |

keeply folders

List all your folders.

keeply folders
keeply folders --json

keeply tags

List all your tags, sorted by usage.

keeply tags
keeply tags --json

keeply config

Manage CLI configuration.

keeply config set-key <api-key>  # Set an API key manually (for CI/scripts)
keeply config show               # Show current config
keeply config clear              # Remove stored credentials

Using with AI agents

All commands support --json output for clean, machine-readable data.

# Give an AI agent your full bookmark list
keeply list --limit 0 --json | llm "what topics do I read most about?"

# Search and summarize
keeply search "python" --json | llm "summarize these links"

# Extract just URLs
keeply list --folder "To Read" --json | jq '.[].url'

# Save a bookmark from a script
URL="https://example.com"
TITLE=$(curl -s "$URL" | grep -oP '(?<=<title>)[^<]+')
keeply add "$URL" --title "$TITLE" --folder "Inbox"

# Find bookmarks modified recently and process them
keeply list --json | jq '[.[] | select(.updatedAt > "2026-01-01")]'

Output formats

Default (human-readable)

1. My Bookmark Title
   https://example.com/some/page
   #typescript  #tools
   Note: Really useful reference
   id: cm3x7abc123  ·  3/15/2026

2. Another Bookmark
   https://another.com
   ...

Short (--short)

  1. My Bookmark Title                         https://example.com/some/page
  2. Another Bookmark                          https://another.com

JSON (--json)

Standard JSON array of bookmark objects, suitable for piping to jq, AI agents, or any other tool.