WebCull
En
Fr
Es
De
Documentation CLI and agents
CLI and agents

WebCull CLI

Install, authorize, and use the WebCull CLI to find, create, and update bookmarks.

Synopsis

WebCull CLI command reference

The WebCull CLI is a command line tool for finding, creating, and updating bookmarks from a terminal or automation workflow. Commands return JSON by default and are designed to work with large bookmark accounts through limits, paging, field selection, and output budgets.

webcull <command> [options]
Command
webcull
Package
@webcull/cli
Config path
~/.config/webcull/config.json, or the path set by WEBCULL_CONFIG.
API URL
Defaults to https://api.webcull.com. Override with WEBCULL_API_URL.
Authentication

Authorize the CLI before running account commands

webcull login
webcull auth login
webcull whoami
webcull limits

webcull login starts a short-lived browser approval flow. The terminal shows a pairing code, the browser shows the same code, and approval creates a CLI token for bookmark read and write commands.

Only approve a login that you started. Compare the terminal code with the browser code before approving.

login
Starts browser authorization and stores the CLI token after approval.
auth login
Alias for login.
whoami
Prints the authorized account as JSON.
limits
Prints current CLI usage limits and remaining request capacity.
Read commands

Start broad, then fetch specific bookmark records

webcull bookmarks count [--path <path>]
webcull bookmarks tree [--path <path>] [--max-depth <n>] [--per-parent-limit <n>]
webcull bookmarks search --query <query> [--sort <sort>]
webcull bookmarks get --ids <ids>
bookmarks count
Counts children under a bookmark path. The default path is /.
bookmarks tree
Returns a bounded tree from a path. Defaults include --limit 50, --max-depth 2, and --max-chars 12000.
bookmarks search
Searches bookmark metadata. The default result limit is 25 and the default sort is modified_desc.
bookmarks get
Fetches specific bookmarks by ID. Pass one ID, comma-separated IDs, or --ids.

Prefer count or a shallow tree before fetching larger result sets. Use get after you know the bookmark IDs you need.

Output controls

Limit payload size and choose output fields

webcull bookmarks tree --path / --max-depth 1 --limit 25 --max-chars 8000 --fields id,type,title,modified
webcull bookmarks get --ids 123,456 --fields id,title,url,notes --max-metadata-chars 1500 --format json
webcull bookmarks search --query 'github api' --limit 20 --format jsonl
--limit <n>
Maximum number of results returned by commands that list bookmarks.
--page <n>
Page number for commands that support paged results. Pages start at 1.
--max-chars <n>
Maximum response size budget.
--max-metadata-chars <n>
Maximum metadata text included for each bookmark.
--fields <list>
Comma-separated output fields, such as id,title,url,parent_id,modified.
--format json|jsonl
Prints pretty JSON by default. jsonl prints one item per line when the response contains an item list.
Write commands

Create and update bookmarks

webcull bookmarks create --url <url> [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]
webcull bookmarks create --type folder --title <title> [--parent-id <id>] [--dry-run]
webcull bookmarks update <id> [--url <url>] [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]
--url <url>
Creates or updates a bookmark URL. Required when creating a bookmark.
--type folder
Creates a folder. Folder creation requires --title and does not accept --url.
--title <title>
Sets the bookmark or folder title.
--notes <text>
Sets bookmark notes.
--tags <tags>
Sets comma-separated tags. Whitespace around each tag is trimmed.
--parent-id <id>
Places the bookmark or folder under a parent by ID.
--parent-path <path>
Places the bookmark or folder under a parent by path. Do not combine with --parent-id.
--dry-run
Validates authentication, scope, throttles, ownership, placement, and E2EE state without saving the change.

Write commands preserve fields that are not included in the command. They do not support bulk writes, recursive writes, automatic folder creation, bookmark-to-folder conversion, folder-to-bookmark conversion, icon upload, or E2EE enable, disable, or key-change flows.

Encrypted accounts

E2EE passphrases stay in hidden terminal prompts

For E2EE accounts, the CLI prompts for the E2EE passphrase only through hidden interactive terminal input. It never accepts E2EE passphrases in arguments, environment variables, config files, stdin pipes, logs, or examples.

Encrypted bookmark fields are encrypted locally before writes and decrypted locally for supported reads. The server receives encrypted values and never receives passphrases, derived keys, passphrase hashes, or decrypted bookmark fields for E2EE validation.

CLI writes are blocked while E2EE conversion is in progress. Finish E2EE conversion in the app before updating bookmarks that still need conversion.

Tokens

CLI tokens are separate from browser sessions

The CLI stores its token in ~/.config/webcull/config.json by default with file mode 0600. Set WEBCULL_CONFIG to use a different path.

The token is separate from browser and extension sessions. Current bookmark CLI tokens include bookmarks:read and bookmarks:write.

Limits

Use throttles as pacing guidance

WebCull limits CLI requests to protect accounts and keep the service responsive. Read commands and write commands have different limits.

Read token
60 requests per minute, 600 per hour, and 3000 per day.
Read user or IP
User and IP limits provide additional account and network protection.
Write token
10 requests per minute, 100 per hour, and 500 per day.
Write user or IP
Write requests have stricter account and network pacing than read requests.
Limits lookup
7 requests per minute. Call webcull limits sparingly.

On a throttled response, wait at least 60 seconds before retrying. Narrow the next request where possible. Dry-run writes use the write throttle because they exercise the write path and ownership checks.