WebCull - Documentation - Authentication

Authentication

Authorize The CLI With A Browser Approval Flow

The CLI uses a short-lived browser approval flow. Approve only requests you initiated from webcull login; approval creates a separate scoped CLI token.

Where Your Access Token Is Stored

CLI sign-in is separate from browser and extension sign-in. Each connected account gets its own access token, which your computer keeps in protected password storage. The CLI settings file lists your connected accounts but never contains their tokens.

Command

Start Login And Verify The Account

webcull login
webcull accounts
webcull whoami --account <account-hash>

webcull login

Starts authorization and opens the browser approval page.

webcull auth login

Alias for webcull login.

webcull accounts

Lists every locally authorized account with its user ID, hash, expiry, and active status without printing tokens.

webcull whoami --account <account-hash>

Prints the authorized account and token expiry.

Multiple Accounts

Keep Several Accounts Logged In At The Same Time

Each successful login adds another local CLI authorization. Use --account <hash|id> to select one account for a command. Without it, ordinary commands use the last successfully accessed account.

webcull accounts
webcull bookmarks count --account abc123 --path /
webcull bookmarks search --account abc123 --query 'project notes' --limit 20

{
  "success": "true",
  "active_account": "abc123",
  "accounts": [
    {
      "number": 1,
      "active": true,
      "user": {
        "id": 42,
        "hash": "abc123",
        "name": "Personal",
        "email": "person@example.com"
      }
    }
  ]
}

Agent selection

Agents should run webcull accounts at the start of a new WebCull context. With one account they use its hash automatically. With several accounts they show a numbered list, ask which account applies, and include that hash on every later command.

Logout

Choose The Account Before Revoking Access

webcull logout
webcull logout --account abc123
webcull logout --account abc123 --local-only

When several accounts are logged in, interactive webcull logout shows a numbered picker. Non-interactive callers receive an account-selection response and must rerun with the intended hash or user ID.

Normal logout revokes the selected server token before removing its local credential. Use --local-only only when WebCull cannot be reached and you still need to remove access from this device. It removes the selected local credential without revoking the server token, which may remain usable until it expires.

Output

Read The Account Response

{
  "success": "true",
  "user": {
    "id": 42,
    "hash": "abc123abc123abc123abc123abc123",
    "email": "person@example.com"
  },
  "scopes": ["bookmarks:read", "bookmarks:write"],
  "expires": 1781300000
}

Use scopes to confirm what this token can do. Read commands require bookmarks:read. Create, update, reminder create, and reminder cancel require bookmarks:write.