npm package: @keeply-link/cli
Description: Keeply CLI — read, save, and manage your bookmarks from the terminal
Latest version: 1.2.6

# keeply-cli

Command-line interface for [Keeply](https://keeply.tools) — 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

```bash
brew tap keeply-link/keeply
brew install keeply
```

### npm (requires Node.js 18+)

```bash
npm install -g @keeply-link/cli
```

### From source

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

---

## Setup

```bash
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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
keeply get cm3x7abc123
keeply get cm3x7abc123 --json
```

---

### `keeply add <url>`

Save a new bookmark.

```bash
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.

```bash
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.

```bash
keeply folders
keeply folders --json
```

---

### `keeply tags`

List all your tags, sorted by usage.

```bash
keeply tags
keeply tags --json
```

---

### `keeply config`

Manage CLI configuration.

```bash
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.

```bash
# 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.