Skip to content

auth.md

Latest commit

 

History

History
89 lines (59 loc) · 3.84 KB

auth.md

File metadata and controls

89 lines (59 loc) · 3.84 KB
Raw
title Sign in
description Connect birdclaw to X through xurl or bird, verify each tool, and choose the moderation write transport.

Sign in

birdclaw keeps its database local. Archive import needs no X credentials. Live reads and writes are delegated to external CLIs:

  • xurl uses the official X API and your own developer app.
  • bird uses the active browser session through X's web API.

Install either tool or both. Transport selection is workflow-specific: sync commands expose --mode, while auth use only controls moderation writes such as block, unblock, mute, and unmute.

On a fresh Birdclaw database, import your X archive before the first live sync. Archive import replaces the bundled demo identity with your account identity. The current auth commands verify transports but do not bind a new database to the authenticated X account.

Set up xurl

Install xurl, register an X developer app, then start OAuth2 authentication. Homebrew is available on macOS; npm and the upstream install script work on macOS and Linux:

# macOS
brew install --cask xdevplatform/tap/xurl

# macOS or Linux
npm install -g @xdevplatform/xurl

xurl auth oauth2 --app my-app
xurl whoami

Alternatively, use xurl's no-sudo install script. Register my-app first by following the xurl authentication guide. The redirect URI configured in the X developer portal must match xurl's configured URI. Treat the client secret as a secret; avoid entering it in shared shell history or exposing it in process listings.

Set up bird

Install bird, sign in to x.com in Safari, Chrome, or Firefox, then verify the detected account:

npm install -g @steipete/bird
bird whoami

bird reads auth_token and ct0 cookies from the selected browser profile. If autodetection misses the right profile, see bird authentication for cookie-source and profile flags.

Verify xurl in birdclaw

birdclaw auth status --json

auth status runs a coarse xurl status probe. It does not probe bird, prove that a specific X API request will succeed, or choose a transport for every command.

  • installed reports whether the xurl executable exists.
  • availableTransport is xurl when xurl auth status succeeds without a known unauthenticated message; otherwise it is local.
  • statusText explains the detected state.
  • rawStatus contains xurl's status output when available.

Use xurl whoami as the end-to-end authentication check. Run xurl auth status for detailed app/token state and bird whoami to verify bird independently.

Choose moderation transport

Persist the preferred transport for block, unblock, mute, and unmute:

birdclaw auth use auto
birdclaw auth use bird
birdclaw auth use xurl

auto tries bird first for moderation writes, then xurl. A command-level --transport flag overrides the saved value. BIRDCLAW_ACTIONS_TRANSPORT overrides the config for one process.

Sync commands do not use this saved moderation setting. Select their source with the command's --mode flag:

birdclaw sync timeline --mode auto
birdclaw sync mentions --mode bird
birdclaw sync likes --mode xurl

Supported modes differ by command; use birdclaw sync <command> --help.

Security

  • xurl stores developer-app credentials and OAuth tokens under ~/.xurl.
  • bird uses browser session cookies. Treat auth_token and ct0 as full account credentials.
  • Use archive-only mode when live access is unnecessary.
  • Set BIRDCLAW_DISABLE_LIVE_WRITES=1 for development or dry runs.

For multiple Birdclaw accounts, use --account <id> on commands that support it. See Configuration.