Fan out first, then focus in
Agents should use the WebCull CLI in a fan-out then focus-in workflow. Start with counts and small result pages. Fetch full bookmark metadata only after candidate IDs are known. Write commands should be used only after the user explicitly asks to create or update bookmarks.
Talk to your bookmarks
This workflow lets a user ask natural questions about their saved bookmarks. The agent should first invite the user to choose a specific folder or use the full bookmark account as context, then fan out across likely matches before progressively narrowing into the details that answer the question.
The conversation should feel like talking to a librarian who knows the topic and the user's saved material. The agent should create curated lists from bookmark metadata first, then use direct search, snapshot content, or fetched page metadata when the account and command options make that available.
bookmarks search queries when the user asks about a topic, tool, person, domain, project, tag, or phrase.Example prompt
Talk to my bookmarks about local-first software. Ask whether I want one folder or my full bookmark account, fan out across likely matches, then narrow into saved metadata, snapshots, fetched page metadata, and related documentation from the same sites.
Organize bookmarks into clearer folders
This workflow is for users who want an agent to help turn a messy bookmark account into a cleaner folder structure. The agent should inspect broad folder counts first, identify folders that are too large or mixed, then propose categories and subcategories before making any changes.
bookmarks count and shallow bookmarks tree calls to find folders with many items, duplicated themes, or mixed topics.Example prompt
Help me organize my bookmarks. Start by finding folders that are too broad or crowded, then suggest a cleaner folder and subfolder structure before making changes.
Analyze bookmarks for workflow improvements
This workflow is read-heavy. The agent should use existing bookmarks to understand how the user works, then suggest practical improvements without immediately reorganizing the account.
Example prompt
How can I improve my bookmarks to help my workflow? Read what I have, find friction, and suggest useful changes without editing anything yet.
Infer interests and suggest useful discoveries
This workflow uses the user's bookmarks as context for recommendations. The agent should infer interests from saved topics, tools, creators, entertainment links, and research areas, then suggest things the user may want to explore next.
Example prompt
Based on my bookmarks, what topics, tools, media, or entertainment would you recommend I explore next? Explain what bookmark patterns led to each suggestion.
Build a learning path from a folder
This workflow turns a folder into a guided sequence. The agent should infer the topic, inspect the saved material, then arrange bookmarks into a path that helps the user move from orientation to deeper study.
Example prompt
Turn this folder into a learning path. Infer the topic, sort my bookmarks from beginner to advanced, and tell me what is missing.
Prepare a folder for a public Collection
This workflow reviews a folder before the user makes it public. The agent should look for anything that would make the Collection unclear, incomplete, private, or hard for visitors to scan.
Example prompt
Review this folder before I make it public. Find private links, weak titles, missing descriptions, bad icons, unclear folder names, and anything that should be reordered.
Keep each request intentionally small
Use --max-chars, --limit, --page, --fields, and --max-metadata-chars on every bookmark command. When searching blind, start with bookmarks count or bookmarks tree --limit 25 --max-chars 8000.
When the result is too broad, reduce fields first, then reduce metadata characters, then page through results. Do not request full notes or all metadata until the target IDs are narrowed.
Run CLI calls sequentially
Do not run WebCull CLI calls in parallel. Wait at least 1 second between CLI calls, at least 2 seconds after tree or search calls, and at least 2 seconds between pages. Use webcull limits sparingly because it is limited to 7 calls per minute. If the API returns throttled, wait at least 60 seconds and narrow the next request.
Read commands allow 60 requests per minute, 600 per hour, and 3000 per day for each CLI token. Write commands are stricter: 10 per minute, 100 per hour, and 500 per day. Account and network limits may also apply.
Only write when the user asks to create or update bookmarks
Only use webcull bookmarks create or webcull bookmarks update <id> when the user explicitly asks for a write. Do not use the CLI for bulk writes, recursive writes, implicit organization, type conversion, icon upload, or E2EE account state changes.
Prefer --dry-run before a real write when validating parent placement, ownership, or E2EE state. Preserve unedited fields by sending only the field the user asked to change.
Never expose encrypted-account passphrases
Never provide an E2EE passphrase through CLI arguments, environment variables, config, stdin, logs, or examples. The CLI prompts only through hidden interactive terminal input.
For encrypted accounts, bookmark text search automatically uses bounded local decrypted search when needed. Keep limits such as --limit and --max-scan-rows tight. If E2EE conversion is in progress, do not force a write. Ask the user to finish conversion in the app.
Example command sequence
webcull bookmarks count --path /
webcull bookmarks tree --path / --max-depth 1 --limit 25 --max-chars 8000 --fields id,type,title,modified
webcull bookmarks search --query 'github api' --limit 20 --max-chars 8000 --fields id,title,url,parent_id
webcull bookmarks search --query 'github api' --limit 20 --max-scan-rows 500
webcull bookmarks get --ids 123,456 --fields id,title,url,notes --max-metadata-chars 1500
webcull bookmarks create --url https://example.com --title Example --dry-run
webcull bookmarks update 456 --title "New title" --dry-run