Karakeep

Use flowbot bookmark for capability karakeep.
CLI root is bookmark — do not invent flowbot karakeep unless cli.md lists it as an alias.
Prefer the workflows below; load references/cli.md only when you need a flag or subcommand not covered here.

CLI limits: Tag attach/detach and health are capability ops without CLI commands; inspect tags via bookmark get.

JSON fields: Single-item -o json uses field id. bookmark list|search -o json returns {data, page}; page with page.next_cursor (opaque, often >100 chars) when more pages exist.

Setup

1. Ensure CLI auth: flowbot login
2. Set server via FLOWBOT_SERVER_URL or --server-url; optional --profile, --debug / -d
3. Prefer -o json when parsing results programmatically
4. Destructive commands often need -y / --yes in non-interactive sessions — check cli.md
5. Token scopes: service:karakeep:read / service:karakeep:write

Workflows

Save a URL from a chat message

When a user shares a URL they want to save:

1. flowbot bookmark check-url -u <url>
2. flowbot bookmark create -u <url>
3. Report back with the bookmark details including the assigned ID.

Find and review bookmarks

When a user wants to find previously saved content:

1. flowbot bookmark search -q "<keywords>" --limit 10 -o json
2. Or page with flowbot bookmark list -n 100 -o json; follow page.next_cursor until absent. Filter archived: false for unread.
3. flowbot bookmark get <id>
4. Present the bookmark details to the user.

Archive a bookmark

When a user wants to archive a saved URL:

1. flowbot bookmark archive <id> -y
2. Confirm archive status from the command output.

Troubleshooting