Start

Sign in

GitHub Edit page

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.