@keeply-link/cli 1.0.0

package/README.md

@@ -0,0 +1,279 @@
+# 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.
+
+---
+
+## 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
+
+Generate an API key in the Keeply web app under **Settings → API Keys**. Your key needs at minimum these scopes:
+
+| Scope             | Used by                        |
+| ----------------- | ------------------------------ |
+| `read_bookmarks`  | `list`, `get`, `search`        |
+| `create_bookmark` | `add`                          |
+| `update_bookmark` | `update`                       |
+| `read_folders`    | `folders`, `--folder` filters  |
+| `search_bookmarks`| `search`                       |
+
+```bash
+# Connect to Keeply (verifies your key before saving)
+keeply config set-key <your-api-key>
+
+# Check current config
+keeply config show
+```
+
+Config is stored at `~/.config/keeply-cli/config.json`.
+
+---
+
+## Commands
+
+### `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>`
+
+Full-text search powered by MeiliSearch — searches 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 API key (verifies first)
+keeply config show               # Show current config
+keeply config clear              # Remove stored API key
+```
+
+---
+
+## Using with AI agents
+
+All commands support `--json` output for clean, machine-readable data. This makes it easy to pipe bookmarks into any AI agent or script.
+
+```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.
+
+---
+
+## API scopes reference
+
+When creating an API key in Keeply, select the scopes you need:
+
+| Command | Required scope |
+|---------|---------------|
+| `list`, `get` | `read_bookmarks` |
+| `search` | `search_bookmarks` |
+| `add` | `create_bookmark` |
+| `update` | `update_bookmark` |
+| `folders` | `read_folders` |
+| `tags` | `read_bookmarks` |

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+import type { Bookmark, Folder, Tag, CreateBookmarkPayload, UpdateBookmarkPayload } from './types.js';
+export declare class KeeplyApi {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl: string);
+    private get headers();
+    private request;
+    whoami(): Promise<{
+        email: string;
+        name?: string;
+        isPro: boolean;
+    }>;
+    listBookmarks(includeDeleted?: boolean): Promise<Bookmark[]>;
+    getBookmark(id: string): Promise<Bookmark>;
+    createBookmark(payload: CreateBookmarkPayload): Promise<Bookmark>;
+    updateBookmark(id: string, payload: UpdateBookmarkPayload): Promise<Bookmark>;
+    searchBookmarks(query: string): Promise<Bookmark[]>;
+    listFolders(): Promise<Folder[]>;
+    listTags(): Promise<Tag[]>;
+}

package/dist/api.js

@@ -0,0 +1,68 @@
+export class KeeplyApi {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    get headers() {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `ApiKey ${this.apiKey}`,
+        };
+    }
+    async request(path, init) {
+        const url = `${this.baseUrl.replace(/\/$/, '')}${path}`;
+        const res = await fetch(url, { ...init, headers: { ...this.headers, ...init?.headers } });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            const msg = Array.isArray(body.message) ? body.message.join(', ') : (body.message ?? `HTTP ${res.status}`);
+            throw new Error(msg);
+        }
+        // 204 No Content
+        if (res.status === 204)
+            return undefined;
+        return res.json();
+    }
+    async whoami() {
+        return this.request('/users/me');
+    }
+    // Bookmarks
+    async listBookmarks(includeDeleted = false) {
+        const qs = includeDeleted ? '?includeDeleted=true' : '';
+        return this.request(`/bookmarks${qs}`);
+    }
+    async getBookmark(id) {
+        // No single-get endpoint exists; fetch all and filter
+        const all = await this.listBookmarks();
+        const found = all.find((b) => b.id === id);
+        if (!found)
+            throw new Error(`Bookmark ${id} not found`);
+        return found;
+    }
+    async createBookmark(payload) {
+        return this.request('/bookmarks', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    async updateBookmark(id, payload) {
+        return this.request(`/bookmarks/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+        });
+    }
+    async searchBookmarks(query) {
+        const res = await this.request(`/search?q=${encodeURIComponent(query)}`);
+        return res.hits;
+    }
+    // Folders
+    async listFolders() {
+        return this.request('/folders');
+    }
+    // Tags
+    async listTags() {
+        const data = await this.request('/bookmarks/sidebar-data');
+        return data.tags;
+    }
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAddCommand(program: Command): void;

package/dist/commands/add.js

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { printError, printSuccess } from '../format.js';
+export function registerAddCommand(program) {
+    program
+        .command('add <url>')
+        .description('Save a new bookmark')
+        .option('-t, --title <title>', 'Bookmark title')
+        .option('-n, --note <note>', 'Personal note')
+        .option('-f, --folder <name|id>', 'Folder name or ID')
+        .option('--tags <tags>', 'Comma-separated tag names (must already exist)')
+        .option('--json', 'Output created bookmark as JSON')
+        .action(async (url, opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            let folderId;
+            let tagIds;
+            if (opts.folder) {
+                const folders = await api.listFolders();
+                const match = folders.find((f) => f.name.toLowerCase() === opts.folder.toLowerCase() || f.id === opts.folder);
+                if (!match) {
+                    printError(`Folder "${opts.folder}" not found. Create it in the web app first.`);
+                    process.exit(1);
+                }
+                folderId = match.id;
+            }
+            if (opts.tags) {
+                const tagNames = opts.tags.split(',').map((t) => t.trim().toLowerCase());
+                const allTags = await api.listTags();
+                tagIds = [];
+                for (const name of tagNames) {
+                    const found = allTags.find((t) => t.name === name);
+                    if (!found) {
+                        printError(`Tag "${name}" not found. Create it in the web app first.`);
+                        process.exit(1);
+                    }
+                    tagIds.push(found.id);
+                }
+            }
+            const bookmark = await api.createBookmark({
+                url,
+                title: opts.title,
+                note: opts.note,
+                folderId,
+                tagIds,
+            });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(bookmark, null, 2));
+                return;
+            }
+            printSuccess(`Saved  ${chalk.bold(bookmark.title ?? url)}`);
+            console.log(chalk.dim(`id: ${bookmark.id}`));
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to save bookmark');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerConfigCommands(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { conf, getConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { printError, printSuccess } from '../format.js';
+export function registerConfigCommands(program) {
+    const config = program.command('config').description('Manage CLI configuration');
+    config
+        .command('set-key <api-key>')
+        .description('Set your Keeply API key')
+        .action(async (apiKey) => {
+        const url = conf.get('apiUrl');
+        process.stdout.write('Verifying API key… ');
+        try {
+            const api = new KeeplyApi(apiKey, url);
+            const user = await api.whoami();
+            conf.set('apiKey', apiKey);
+            process.stdout.write('\n');
+            printSuccess(`Connected as ${chalk.bold(user.email)}${user.isPro ? chalk.cyan(' (Pro)') : ''}`);
+            console.log(chalk.dim(`Config saved to ${conf.path}`));
+        }
+        catch (err) {
+            process.stdout.write('\n');
+            printError(err instanceof Error ? err.message : 'Failed to verify key');
+            process.exit(1);
+        }
+    });
+    config
+        .command('show')
+        .description('Show current configuration')
+        .action(() => {
+        const { apiKey } = getConfig();
+        console.log(`API Key  ${apiKey ? chalk.dim(`${apiKey.slice(0, 8)}…`) : chalk.red('not set')}`);
+        console.log(chalk.dim(`\nConfig file: ${conf.path}`));
+    });
+    config
+        .command('clear')
+        .description('Remove stored API key')
+        .action(() => {
+        conf.set('apiKey', '');
+        printSuccess('API key cleared');
+    });
+}

package/dist/commands/folders.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerFoldersCommand(program: Command): void;

package/dist/commands/folders.js

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { formatFolder, printError } from '../format.js';
+export function registerFoldersCommand(program) {
+    program
+        .command('folders')
+        .description('List all folders')
+        .option('--json', 'Output raw JSON')
+        .action(async (opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            const folders = await api.listFolders();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(folders, null, 2));
+                return;
+            }
+            if (folders.length === 0) {
+                console.log(chalk.dim('No folders yet.'));
+                return;
+            }
+            console.log('');
+            folders.forEach((f, i) => console.log(formatFolder(f, i)));
+            console.log(chalk.dim(`\n${folders.length} folder${folders.length !== 1 ? 's' : ''}`));
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to list folders');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/get.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerGetCommand(program: Command): void;

package/dist/commands/get.js

@@ -0,0 +1,27 @@
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { formatBookmark, printError } from '../format.js';
+export function registerGetCommand(program) {
+    program
+        .command('get <id>')
+        .description('Get a single bookmark by ID')
+        .option('--json', 'Output raw JSON')
+        .action(async (id, opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            const bookmark = await api.getBookmark(id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(bookmark, null, 2));
+                return;
+            }
+            console.log('');
+            console.log(formatBookmark(bookmark));
+            console.log('');
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to get bookmark');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerListCommand(program: Command): void;

package/dist/commands/list.js

@@ -0,0 +1,73 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { formatBookmark, formatBookmarkShort, paginate, printPaginationInfo, printError } from '../format.js';
+export function registerListCommand(program) {
+    program
+        .command('list')
+        .alias('ls')
+        .description('List bookmarks')
+        .option('-f, --folder <name|id>', 'Filter by folder name or ID')
+        .option('-t, --tag <name>', 'Filter by tag name')
+        .option('-a, --archived', 'Show archived bookmarks only')
+        .option('-l, --limit <n>', 'Results per page (0 = no pagination)', '20')
+        .option('-p, --page <n>', 'Page number', '1')
+        .option('-s, --short', 'Compact one-line output')
+        .option('--json', 'Output raw JSON (for piping to AI agents)')
+        .action(async (opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            let bookmarks = await api.listBookmarks();
+            // Filters
+            if (opts.folder) {
+                const folders = await api.listFolders();
+                const match = folders.find((f) => f.name.toLowerCase() === opts.folder.toLowerCase() || f.id === opts.folder);
+                if (!match) {
+                    printError(`Folder "${opts.folder}" not found`);
+                    process.exit(1);
+                }
+                bookmarks = bookmarks.filter((b) => b.folderId === match.id);
+            }
+            if (opts.tag) {
+                const tagLower = opts.tag.toLowerCase();
+                bookmarks = bookmarks.filter((b) => b.tags.some((t) => t.tag.name.toLowerCase() === tagLower));
+            }
+            if (opts.archived) {
+                bookmarks = bookmarks.filter((b) => b.archived);
+            }
+            else {
+                bookmarks = bookmarks.filter((b) => !b.archived && !b.deletedAt);
+            }
+            // JSON output (no pagination)
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(bookmarks, null, 2));
+                return;
+            }
+            // Paginate
+            const limit = parseInt(opts.limit, 10);
+            const page = parseInt(opts.page, 10);
+            const { items, total, pages } = paginate(bookmarks, page, limit);
+            if (items.length === 0) {
+                console.log(chalk.dim('No bookmarks found.'));
+                return;
+            }
+            console.log('');
+            if (opts.short) {
+                items.forEach((b, i) => console.log(formatBookmarkShort(b, (page - 1) * limit + i)));
+            }
+            else {
+                items.forEach((b, i) => {
+                    console.log(formatBookmark(b, (page - 1) * limit + i));
+                    if (i < items.length - 1)
+                        console.log('');
+                });
+            }
+            printPaginationInfo(page, pages, total, items.length);
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to list bookmarks');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSearchCommand(program: Command): void;

package/dist/commands/search.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { formatBookmark, formatBookmarkShort, printError } from '../format.js';
+export function registerSearchCommand(program) {
+    program
+        .command('search <query>')
+        .description('Full-text search across your bookmarks')
+        .option('-s, --short', 'Compact one-line output')
+        .option('--json', 'Output raw JSON')
+        .action(async (query, opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            const bookmarks = await api.searchBookmarks(query);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(bookmarks, null, 2));
+                return;
+            }
+            if (bookmarks.length === 0) {
+                console.log(chalk.dim(`No results for "${query}"`));
+                return;
+            }
+            console.log('');
+            if (opts.short) {
+                bookmarks.forEach((b, i) => console.log(formatBookmarkShort(b, i)));
+            }
+            else {
+                bookmarks.forEach((b, i) => {
+                    console.log(formatBookmark(b, i));
+                    if (i < bookmarks.length - 1)
+                        console.log('');
+                });
+            }
+            console.log(chalk.dim(`\n${bookmarks.length} result${bookmarks.length !== 1 ? 's' : ''} for "${query}"`));
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Search failed');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/tags.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerTagsCommand(program: Command): void;

package/dist/commands/tags.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { formatTag, printError } from '../format.js';
+export function registerTagsCommand(program) {
+    program
+        .command('tags')
+        .description('List all tags')
+        .option('--json', 'Output raw JSON')
+        .action(async (opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            const tags = await api.listTags();
+            const sorted = tags.sort((a, b) => b.count - a.count);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(sorted, null, 2));
+                return;
+            }
+            if (sorted.length === 0) {
+                console.log(chalk.dim('No tags yet.'));
+                return;
+            }
+            console.log('');
+            sorted.forEach((t, i) => console.log(formatTag(t, i)));
+            console.log(chalk.dim(`\n${sorted.length} tag${sorted.length !== 1 ? 's' : ''}`));
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to list tags');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+import { requireConfig } from '../config.js';
+import { KeeplyApi } from '../api.js';
+import { printError, printSuccess } from '../format.js';
+export function registerUpdateCommand(program) {
+    program
+        .command('update <id>')
+        .description('Update a bookmark')
+        .option('--url <url>', 'New URL')
+        .option('-t, --title <title>', 'New title')
+        .option('-n, --note <note>', 'New note')
+        .option('-f, --folder <name|id>', 'Move to folder')
+        .option('--unfolder', 'Remove from folder (move to unsorted)')
+        .option('--tags <tags>', 'Replace tags (comma-separated names)')
+        .option('--archive', 'Mark as archived')
+        .option('--unarchive', 'Remove archived status')
+        .option('--json', 'Output updated bookmark as JSON')
+        .action(async (id, opts) => {
+        const { apiKey, apiUrl } = requireConfig();
+        const api = new KeeplyApi(apiKey, apiUrl);
+        try {
+            const payload = {};
+            if (opts.url)
+                payload.url = opts.url;
+            if (opts.title)
+                payload.title = opts.title;
+            if (opts.note)
+                payload.note = opts.note;
+            if (opts.archive)
+                payload.archived = true;
+            if (opts.unarchive)
+                payload.archived = false;
+            if (opts.unfolder) {
+                payload.folderId = null;
+            }
+            else if (opts.folder) {
+                const folders = await api.listFolders();
+                const match = folders.find((f) => f.name.toLowerCase() === opts.folder.toLowerCase() || f.id === opts.folder);
+                if (!match) {
+                    printError(`Folder "${opts.folder}" not found`);
+                    process.exit(1);
+                }
+                payload.folderId = match.id;
+            }
+            if (opts.tags) {
+                const tagNames = opts.tags.split(',').map((t) => t.trim().toLowerCase());
+                const allTags = await api.listTags();
+                const tagIds = [];
+                for (const name of tagNames) {
+                    const found = allTags.find((t) => t.name === name);
+                    if (!found) {
+                        printError(`Tag "${name}" not found`);
+                        process.exit(1);
+                    }
+                    tagIds.push(found.id);
+                }
+                payload.tagIds = tagIds;
+            }
+            if (Object.keys(payload).length === 0) {
+                printError('No changes specified. Use --help to see options.');
+                process.exit(1);
+            }
+            const bookmark = await api.updateBookmark(id, payload);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(bookmark, null, 2));
+                return;
+            }
+            printSuccess(`Updated  ${chalk.bold(bookmark.title ?? bookmark.url)}`);
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : 'Failed to update bookmark');
+            process.exit(1);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import Conf from 'conf';
+interface Schema {
+    apiKey: string;
+    apiUrl: string;
+}
+export declare const conf: Conf<Schema>;
+export declare function getConfig(): Schema;
+export declare function requireConfig(): Schema;
+export {};

package/dist/config.js

@@ -0,0 +1,25 @@
+import Conf from 'conf';
+import { homedir } from 'os';
+import { join } from 'path';
+export const conf = new Conf({
+    projectName: 'keeply-cli',
+    cwd: join(homedir(), '.config', 'keeply-cli'),
+    defaults: {
+        apiKey: '',
+        apiUrl: 'https://api.keeply.tools',
+    },
+});
+export function getConfig() {
+    return {
+        apiKey: conf.get('apiKey'),
+        apiUrl: conf.get('apiUrl'),
+    };
+}
+export function requireConfig() {
+    const config = getConfig();
+    if (!config.apiKey) {
+        console.error('Not configured. Run: keeply config set-key <api-key>');
+        process.exit(1);
+    }
+    return config;
+}

package/dist/format.d.ts

@@ -0,0 +1,13 @@
+import type { Bookmark, Folder, Tag } from './types.js';
+export declare function formatBookmark(b: Bookmark, index?: number): string;
+export declare function formatBookmarkShort(b: Bookmark, index?: number): string;
+export declare function formatFolder(f: Folder, index?: number): string;
+export declare function formatTag(t: Tag, index?: number): string;
+export declare function paginate<T>(items: T[], page: number, limit: number): {
+    items: T[];
+    total: number;
+    pages: number;
+};
+export declare function printPaginationInfo(page: number, pages: number, total: number, shown: number): void;
+export declare function printError(msg: string): void;
+export declare function printSuccess(msg: string): void;

package/dist/format.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+// ── Bookmark formatting ──────────────────────────────────────────────────────
+export function formatBookmark(b, index) {
+    const lines = [];
+    const num = index !== undefined ? chalk.dim(`${index + 1}. `) : '';
+    const title = b.title ? chalk.white.bold(b.title) : chalk.dim('(no title)');
+    lines.push(`${num}${title}`);
+    lines.push(`   ${chalk.cyan(b.url)}`);
+    const meta = [];
+    if (b.tags.length > 0) {
+        const tagStr = b.tags.map((t) => chalk.magenta(`#${t.tag.name}`)).join(' ');
+        meta.push(tagStr);
+    }
+    if (b.archived)
+        meta.push(chalk.yellow('[archived]'));
+    if (meta.length > 0)
+        lines.push(`   ${meta.join('  ')}`);
+    if (b.note) {
+        lines.push(`   ${chalk.dim('Note:')} ${chalk.italic(b.note)}`);
+    }
+    lines.push(`   ${chalk.dim(`id: ${b.id}  ·  ${new Date(b.createdAt).toLocaleDateString()}`)}`);
+    return lines.join('\n');
+}
+export function formatBookmarkShort(b, index) {
+    const num = index !== undefined ? chalk.dim(`${String(index + 1).padStart(3)}. `) : '';
+    const title = (b.title ?? '(no title)').slice(0, 50).padEnd(50);
+    const url = b.url.slice(0, 55);
+    return `${num}${chalk.white(title)}  ${chalk.dim(url)}`;
+}
+// ── Folder formatting ────────────────────────────────────────────────────────
+export function formatFolder(f, index) {
+    const num = index !== undefined ? chalk.dim(`${index + 1}. `) : '';
+    const count = f._count ? chalk.dim(` (${f._count.bookmarks})`) : '';
+    return `${num}${chalk.white.bold(f.name)}${count}  ${chalk.dim(f.id)}`;
+}
+// ── Tag formatting ───────────────────────────────────────────────────────────
+export function formatTag(t, index) {
+    const num = index !== undefined ? chalk.dim(`${index + 1}. `) : '';
+    return `${num}${chalk.magenta(`#${t.name}`)}  ${chalk.dim(`${t.count} bookmark${t.count !== 1 ? 's' : ''}`)}`;
+}
+// ── Paginate ─────────────────────────────────────────────────────────────────
+export function paginate(items, page, limit) {
+    const total = items.length;
+    const pages = limit > 0 ? Math.ceil(total / limit) : 1;
+    const sliced = limit > 0 ? items.slice((page - 1) * limit, page * limit) : items;
+    return { items: sliced, total, pages };
+}
+export function printPaginationInfo(page, pages, total, shown) {
+    if (pages <= 1) {
+        console.log(chalk.dim(`\n${total} bookmark${total !== 1 ? 's' : ''}`));
+    }
+    else {
+        console.log(chalk.dim(`\nPage ${page}/${pages}  ·  showing ${shown} of ${total}  ·  use --page and --limit to navigate`));
+    }
+}
+// ── Errors ───────────────────────────────────────────────────────────────────
+export function printError(msg) {
+    console.error(chalk.red(`✖ ${msg}`));
+}
+export function printSuccess(msg) {
+    console.log(chalk.green(`✔ ${msg}`));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { registerConfigCommands } from './commands/config.js';
+import { registerListCommand } from './commands/list.js';
+import { registerGetCommand } from './commands/get.js';
+import { registerAddCommand } from './commands/add.js';
+import { registerUpdateCommand } from './commands/update.js';
+import { registerSearchCommand } from './commands/search.js';
+import { registerFoldersCommand } from './commands/folders.js';
+import { registerTagsCommand } from './commands/tags.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+const program = new Command();
+program
+    .name('keeply')
+    .description('Keeply CLI — manage your bookmarks from the terminal')
+    .version(version);
+registerConfigCommands(program);
+registerListCommand(program);
+registerGetCommand(program);
+registerAddCommand(program);
+registerUpdateCommand(program);
+registerSearchCommand(program);
+registerFoldersCommand(program);
+registerTagsCommand(program);
+program.parse();

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export interface Bookmark {
+    id: string;
+    url: string;
+    title?: string;
+    description?: string;
+    note?: string;
+    archived: boolean;
+    deletedAt?: string | null;
+    folderId?: string | null;
+    tags: {
+        tag: {
+            id: string;
+            name: string;
+        };
+    }[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    _count?: {
+        bookmarks: number;
+    };
+}
+export interface Tag {
+    id: string;
+    name: string;
+    count: number;
+}
+export interface SidebarData {
+    folders: {
+        id: string;
+        name: string;
+        count: number;
+    }[];
+    tags: {
+        id: string;
+        name: string;
+        count: number;
+    }[];
+}
+export interface CreateBookmarkPayload {
+    url: string;
+    title?: string;
+    description?: string;
+    note?: string;
+    folderId?: string;
+    tagIds?: string[];
+}
+export interface UpdateBookmarkPayload {
+    url?: string;
+    title?: string;
+    description?: string;
+    note?: string;
+    folderId?: string | null;
+    archived?: boolean;
+    tagIds?: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@keeply-link/cli",
+  "version": "1.0.0",
+  "description": "Keeply CLI — read, save, and manage your bookmarks from the terminal",
+  "type": "module",
+  "bin": {
+    "keeply": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "build:bundle": "esbuild dist/index.js --bundle --platform=node --target=node18 --format=cjs --outfile=bundle/keeply.cjs",
+    "build:binary": "npm run build && npm run build:bundle && pkg bundle/keeply.cjs --targets node18-linux-x64,node18-macos-x64,node18-macos-arm64 --output-path binaries/ --compress GZip",
+    "build:binary:local": "npm run build && npm run build:bundle && pkg bundle/keeply.cjs --targets node18-macos-arm64 --output-path binaries/"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "conf": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@yao-pkg/pkg": "^5.12.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keeply-link/keeply-cli"
+  },
+  "homepage": "https://keeply.tools"
+}