### Install Birdclaw via Homebrew, npm, or from source

Source: https://context7.com/steipete/birdclaw/llms.txt

Installation instructions for Birdclaw using different package managers or building from source. Includes optional setup for live transports and AI integration.

```bash
# Homebrew (macOS / Linux)
brew install steipete/tap/birdclaw
birdclaw --version
```

```bash
# npm / pnpm (global)
pnpm add -g birdclaw
# or
npm install -g birdclaw
```

```bash
# From source
git clone https://github.com/steipete/birdclaw.git
cd birdclaw
fnm use          # reads .node-version (Node 25.8.1 or 26.x)
pnpm install
pnpm build
node ./bin/birdclaw.mjs --version
```

```bash
# Optional live transports
brew install xdevplatform/tap/xurl && xurl auth login   # official API
brew install steipete/tap/bird    && bird auth import-cookies  # cookie-backed
```

```bash
# Optional AI inbox scoring
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Start Local Server with Sync

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Starts the local application server and enables background synchronization by default. The server URL is printed to stdout.

```bash
birdclaw serve --sync
```

--------------------------------

### Install Birdclaw from Source

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Install birdclaw from source using fnm for Node version management and pnpm for package installation. Ensure you have Node.js and pnpm installed.

```bash
fnm use
pnpm install
```

--------------------------------

### Example Blocklist File Content

Source: https://github.com/steipete/birdclaw/blob/main/docs/moderation.md

An example of the format accepted by `blocks import`, showing comments, handles, and URLs.

```text
# crypto / AI slop
@jpctan
@SystemDaddyAi
- @Pepe202579 memecoin bait
https://x.com/someone/status/2030857479001960633?s=20
```

--------------------------------

### Install birdclaw from source

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Clone the repository, set up the Node.js version, install dependencies, build the project, and run the CLI from source. This method is useful for development or if you need the latest changes.

```bash
git clone https://github.com/steipete/birdclaw.git
cd birdclaw
fnm use
pnpm install
pnpm build
node ./bin/birdclaw.mjs --version
```

--------------------------------

### Install macOS LaunchAgent for Bookmark Sync

Source: https://context7.com/steipete/birdclaw/llms.txt

Installs a launchd-managed bookmark sync job that runs periodically. Use the `--env-file` option to provide environment variables for non-interactive sessions.

```bash
# Run one bookmark sync manually
birdclaw --json jobs sync-bookmarks --mode auto --limit 100 --max-pages 5 --refresh
```

```bash
# Inspect the last audit entry
tail -n 1 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
```

```bash
# Install the macOS LaunchAgent (runs at load, then every 3 hours)
birdclaw --json jobs install-bookmarks-launchd --program /opt/homebrew/bin/birdclaw
```

```bash
# With a bird env file (for launchd without an interactive browser session)
birdclaw --json jobs install-bookmarks-launchd \
  --program /opt/homebrew/bin/birdclaw \
  --env-file ~/.config/bird/env.sh
```

```bash
# Check launchd status
launchctl print gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
```

```bash
launchctl kickstart -k gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
```

```bash
# Audit log fields: host, timestamps, duration, before/after bookmark counts,
transport, fetched count, backup sync result, any error
tail -n 20 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
```

--------------------------------

### Serve Web App

Source: https://github.com/steipete/birdclaw/blob/main/docs/data-architecture.md

Starts the local web server and background sync. Opens the browser by default unless `--no-open` is specified.

```bash
birdclaw serve
```

--------------------------------

### Birdclaw Configuration File Example

Source: https://github.com/steipete/birdclaw/blob/main/docs/configuration.md

A sample JSON configuration file for Birdclaw, specifying settings for actions, mentions, and backups.

```json
{
  "actions": {
    "transport": "auto"
  },
  "mentions": {
    "dataSource": "bird",
    "birdCommand": "/Users/steipete/Projects/bird/bird"
  },
  "backup": {
    "repoPath": "/Users/steipete/Projects/backup-birdclaw",
    "remote": "https://github.com/steipete/backup-birdclaw.git",
    "autoSync": true,
    "staleAfterSeconds": 900
  }
}
```

--------------------------------

### Install bird via Homebrew

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Install the optional bird tool using Homebrew. This tool provides cookie-backed reads and writes for services where xurl might be rate-limited.

```bash
brew install steipete/tap/bird
bird auth import-cookies
```

--------------------------------

### Install xurl via Homebrew

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Install the optional xurl tool using Homebrew. This tool is used for live reads and writes to services.

```bash
brew install xdevplatform/tap/xurl
xurl auth login
```

--------------------------------

### Install birdclaw via npm/pnpm

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Install birdclaw globally using either pnpm or npm. Verify the installation by checking the version.

```bash
pnpm add -g birdclaw
# or
npm install -g birdclaw

birdclaw --version
```

--------------------------------

### Install Bookmarks Sync as macOS LaunchAgent

Source: https://github.com/steipete/birdclaw/blob/main/docs/jobs.md

Installs a macOS LaunchAgent to run `jobs sync-bookmarks` every 3 hours. Requires specifying the absolute path to the `birdclaw` executable. The plist is written to `~/Library/LaunchAgents/`.

```bash
birdclaw --json jobs install-bookmarks-launchd --program /opt/homebrew/bin/birdclaw
```

--------------------------------

### Run Development Server with Hot Reload

Source: https://context7.com/steipete/birdclaw/llms.txt

Use this command to start the development server. It provides hot reloading for a seamless development experience.

```bash
pnpm dev   # http://localhost:3000
```

--------------------------------

### Install birdclaw via Homebrew

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Use this command to install birdclaw on macOS or Linux using Homebrew. It also shows how to verify the installation.

```bash
brew install steipete/tap/birdclaw
birdclaw --version
```

--------------------------------

### Verify birdclaw installation

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Run these commands to confirm birdclaw is installed correctly and to check its authentication status and database statistics.

```bash
birdclaw --version
birdclaw auth status --json
birdclaw db stats --json
```

--------------------------------

### Birdclaw Configuration Example

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Example JSON configuration for Birdclaw, specifying transport and mention data source settings. `actions.transport` controls live block/mute writes, while `mentions.dataSource` controls live mention reads.

```json
{
	"actions": {
		"transport": "auto"
	},
	"mentions": {
		"dataSource": "bird",
		"birdCommand": "/Users/steipete/Projects/bird/bird"
	}
}
```

--------------------------------

### Run Birdclaw Development Server

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Start the birdclaw development server. This command will build and launch the local web application.

```bash
pnpm dev
```

--------------------------------

### Install Birdclaw with Homebrew

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Install birdclaw using the Homebrew package manager. This is the recommended installation method for macOS users.

```bash
brew install steipete/tap/birdclaw
```

--------------------------------

### Start Local Birdclaw Web App

Source: https://context7.com/steipete/birdclaw/llms.txt

Launches the local React web application. Background sync is enabled by default. Use `--port` to specify a custom port and `--no-sync` to disable background sync.

```bash
# Start with background sync
birdclaw serve
```

```bash
# Start on a custom port, no background sync
birdclaw serve --port 4000 --no-sync
```

--------------------------------

### Birdclaw Backup Configuration

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Example configuration for automatic backup synchronization, specifying repository path, remote URL, and sync interval.

```json
{
	"backup": {
		"repoPath": "/Users/steipete/Projects/backup-birdclaw",
		"remote": "https://github.com/steipete/backup-birdclaw.git",
		"autoSync": true,
		"staleAfterSeconds": 900
	}
}
```

--------------------------------

### Schedule Bookmark Sync with Cron on Linux

Source: https://github.com/steipete/birdclaw/blob/main/docs/jobs.md

Example crontab entry for running `jobs sync-bookmarks` every 3 hours on Linux. Output and errors are redirected to a log file.

```text
0 */3 * * * /usr/local/bin/birdclaw --json jobs sync-bookmarks --mode auto --max-pages 5 --refresh >> ~/.birdclaw/logs/cron.log 2>&1
```

--------------------------------

### Example Research Output (Markdown)

Source: https://github.com/steipete/birdclaw/blob/main/docs/research.md

This is an example of the markdown output generated by the research command. It includes grouped quotes from threads, extracted links, and a list of handles.

```text
# Research: "codex"

## Bookmark · 2026-04-12

> @author: Original tweet about codex agents.
> 
> @reply1: Adds context about scaling.
> @reply2: Pushes back on the framing.

## Bookmark · 2026-04-09

> @another: Different angle on the same topic.

## Links

- https://example.com/codex-explainer
- https://other.example/talk

## Handles

- @author
- @reply1
- @reply2
- @another
```

--------------------------------

### Configure Default Mentions Data Source

Source: https://github.com/steipete/birdclaw/blob/main/docs/mentions.md

Set the default data source for mentions export via the configuration file. This example sets 'bird' as the default and specifies the path to the bird command.

```json
{
  "mentions": {
    "dataSource": "bird",
    "birdCommand": "/Users/steipete/Projects/bird/bird"
  }
}
```

--------------------------------

### Get Database Statistics

Source: https://github.com/steipete/birdclaw/blob/main/docs/archive.md

After importing data, use `db stats` to view row counts for each table and the current schema version, confirming the import's success.

```bash
birdclaw db stats --json
```

--------------------------------

### Initialize Birdclaw Storage and Configuration

Source: https://context7.com/steipete/birdclaw/llms.txt

Initializes the local storage, opens the SQLite database, and sets up the default configuration. It also checks for the availability of live transports.

```bash
birdclaw init
birdclaw auth status --json
```

```json
{ "transports": { "xurl": true, "bird": true, "xweb": false }, "account": null }
```

```bash
birdclaw db stats --json
```

```json
{ "tables": { "tweets": 0, "profiles": 0, "dm_events": 0, ... }, "schemaVersion": 5 }
```

--------------------------------

### Check Launchd Job Status and Rerun

Source: https://github.com/steipete/birdclaw/blob/main/docs/jobs.md

Prints the status of the bookmark sync LaunchAgent and immediately restarts the job using `launchctl kickstart`. This is useful for testing configuration and cookie validity.

```bash
launchctl print gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
```

```bash
launchctl kickstart -k gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
```

```bash
tail -n 1 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
```

--------------------------------

### Sync Followers and Following

Source: https://github.com/steipete/birdclaw/blob/main/docs/sync.md

Records current follower/following state and logs changes. Use `--yes` to enable live xurl fetches; dry runs are default. `--refresh` bypasses the 24-hour cache.

```bash
birdclaw sync followers --json
```

```bash
birdclaw sync following --json
```

```bash
birdclaw sync followers --yes --json
```

```bash
birdclaw sync following --yes --json
```

--------------------------------

### Update birdclaw

Source: https://github.com/steipete/birdclaw/blob/main/docs/install.md

Commands to update birdclaw depending on your installation method: Homebrew, npm, or from source.

```bash
# Homebrew:
brew upgrade birdclaw

# npm:
pnpm up -g birdclaw (or npm i -g birdclaw@latest)

# Source:
git pull && pnpm install && pnpm build
```

--------------------------------

### Pipe Graph Data to jq

Source: https://context7.com/steipete/birdclaw/llms.txt

Example of piping the output of a birdclaw graph command to jq for further JSON processing.

```bash
birdclaw graph top-followers --limit 5 --json | jq '.followers[] | {handle, followersCount}'
```

--------------------------------

### Sync Followers (Live, Limited)

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Performs a live synchronization of followers, limited to one page and allowing partial snapshots. Requires --yes for live sync. Includes JSON output.

```bash
birdclaw sync followers --yes --max-pages 1 --allow-partial --json
```

--------------------------------

### Access Birdclaw Web UI

Source: https://github.com/steipete/birdclaw/blob/main/README.md

The birdclaw web UI is accessible at http://localhost:3000 after starting the development server.

```text
http://localhost:3000
```

--------------------------------

### Sync Following (Live)

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Performs a live synchronization of following, requiring confirmation with --yes. Includes JSON output.

```bash
birdclaw sync following --yes --json
```

--------------------------------

### List All Actionable Items

Source: https://github.com/steipete/birdclaw/blob/main/docs/inbox.md

Returns a flat list of actionable items, ranked by reply state, recency, author influence, and a low-signal heuristic. Use `--json` for machine-readable output.

```bash
birdclaw inbox --json
```

--------------------------------

### Get Graph Events with JSON Output

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Retrieves graph event data in JSON format. This command provides insights into follow graph changes.

```bash
birdclaw graph events --json
```

--------------------------------

### Full Refresh of Followers and Following

Source: https://github.com/steipete/birdclaw/blob/main/docs/follow-graph.md

Executes a full refresh of follower and following data, requiring explicit confirmation with `--yes`. This command fetches live data and updates the local cache.

```bash
birdclaw sync followers --yes --json
birdclaw sync following --yes --json
```

--------------------------------

### Pipe Mentions Export to jq

Source: https://github.com/steipete/birdclaw/blob/main/docs/mentions.md

Pipe the output of `birdclaw mentions export` to `jq` to process the JSON payload. This example extracts the URL and plainText fields from unreplied mentions.

```bash
birdclaw mentions export --unreplied --limit 20 --json | jq '.items[] | {url, plainText}'
```

--------------------------------

### Sync Likes, Bookmarks, and Timeline

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Sync user likes, bookmarks, and home timeline. The `--mode auto` option tries `xurl` first, then falls back to `bird`. Use `--refresh` to force a live fetch. `--json` provides JSON output.

```bash
pnpm cli sync likes --mode auto --limit 100 --refresh --json
```

```bash
pnpm cli sync bookmarks --mode auto --limit 100 --refresh --json
```

```bash
pnpm cli sync bookmarks --mode bird --all --max-pages 5 --limit 100 --refresh --json
```

```bash
pnpm cli sync timeline --limit 100 --refresh --json
```

```bash
pnpm cli sync mention-threads --limit 30 --delay-ms 1500 --timeout-ms 15000 --json
```

--------------------------------

### Sync Following (Dry Run)

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Performs a dry run synchronization of following, outputting results in JSON format. Requires --yes for live sync.

```bash
birdclaw sync following --json
```

--------------------------------

### List, Add, Remove, Record, Sync, and Import Blocks

Source: https://github.com/steipete/birdclaw/blob/main/docs/moderation.md

These commands manage local block entries and interact with live block writes. Use `--account` to specify an account if multiple are configured. The `import` command tolerates comments, blank lines, and various handle/URL formats.

```bash
birdclaw blocks list --account acct_primary --json
```

```bash
birdclaw blocks add @amelia --account acct_primary --json
```

```bash
birdclaw blocks remove @amelia --account acct_primary --json
```

```bash
birdclaw blocks record @amelia --account acct_primary --json
```

```bash
birdclaw blocks sync --account acct_primary --json
```

```bash
birdclaw blocks import ~/triage/blocklist.txt --account acct_primary --json
```

--------------------------------

### Search Imported Tweets

Source: https://github.com/steipete/birdclaw/blob/main/docs/archive.md

Search the imported tweets using full-text search. This example searches for tweets containing the phrase "ship local software" and limits results to 5.

```bash
birdclaw search tweets "ship local software" --limit 5 --json
```

--------------------------------

### Initialize Birdclaw and Check Auth Status

Source: https://github.com/steipete/birdclaw/blob/main/docs/follow-graph.md

Initializes the Birdclaw environment and checks the authentication status. The default account is used unless specified otherwise.

```bash
birdclaw init
birdclaw auth status --json
```

--------------------------------

### Initialize Birdclaw

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Initializes the Birdclaw application. This is typically the first command to run.

```bash
birdclaw init
```

--------------------------------

### Sync Followers (Dry Run)

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Performs a dry run synchronization of followers, outputting results in JSON format. Requires --yes for live sync.

```bash
birdclaw sync followers --json
```

--------------------------------

### Sync Twitter Data

Source: https://github.com/steipete/birdclaw/blob/main/docs/index.md

Pull in mentions, likes, bookmarks, and the home timeline. Use `--refresh` for the timeline to get the latest data and `--all` for bookmarks to sync all of them. The `--json` flag ensures parseable output to stdout.

```bash
birdclaw sync timeline --limit 100 --refresh --json
```

```bash
birdclaw sync bookmarks --mode auto --all --json
```

--------------------------------

### Import Blocklist

Source: https://context7.com/steipete/birdclaw/llms.txt

Bulk import a blocklist from a file. The file can contain handles, IDs, URLs, comments, and bulleted items.

```bash
cat ~/triage/blocklist.txt
# # crypto / AI slop
# @jpctan
# @SystemDaddyAi
# - @Pepe202579 memecoin bait
# https://x.com/someone/status/2030857479001960633?s=20
birdclaw blocks import ~/triage/blocklist.txt --account acct_primary --json
```

--------------------------------

### Get User Information

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Retrieves detailed information about a user, including their DM context and tweet history. Options like `--resolve-profiles` and `--no-xurl-fallback` control data fetching and fallback mechanisms. Use `--current-affiliation` to filter by a specific affiliation.

```bash
pnpm cli whois "blacksmith guy" --context 4 --no-xurl-fallback --json
```

```bash
pnpm cli whois "github guy" --current-affiliation github --exclude-domain-only --no-xurl-fallback
```

```bash
pnpm cli whois "blacksmith" --tweets --context 4 --no-xurl-fallback --json
```

--------------------------------

### Basic Birdclaw CLI Usage

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Illustrates the general structure for invoking birdclaw commands with global flags and subcommands.

```text
birdclaw [global flags] <subcommand> [args]
```

--------------------------------

### Sync Bookmarks with Scheduler-Friendly Defaults

Source: https://github.com/steipete/birdclaw/blob/main/docs/jobs.md

Use this command for scheduled bookmark synchronization. It includes defaults suitable for cron jobs, generates JSONL audit entries, and uses lock files to prevent overlapping runs. Exits non-zero on failure for scheduler retries.

```bash
birdclaw --json jobs sync-bookmarks --mode auto --limit 100 --max-pages 5 --refresh
```

--------------------------------

### Basic Compose Commands

Source: https://github.com/steipete/birdclaw/blob/main/docs/compose.md

Use these commands to post, reply, or send a DM. They utilize the active live transport by default and do not leave half-written states on failure.

```bash
birdclaw compose post "Ship local software."
birdclaw compose reply tweet_004 "On it."
birdclaw compose dm dm_003 "Send it over."
```

--------------------------------

### Configure Environment Variables for Launchd

Source: https://github.com/steipete/birdclaw/blob/main/docs/jobs.md

Create and set environment variables for scheduled processes, such as `AUTH_TOKEN` and `CT0` cookies needed by the `bird` transport. This script ensures sensitive credentials are not hardcoded in the plist.

```bash
mkdir -p ~/.config/bird
chmod 700 ~/.config/bird
cat > ~/.config/bird/env.sh <<'SH'
export AUTH_TOKEN="..."
export CT0="..."
SH
chmod 600 ~/.config/bird/env.sh
```

```bash
birdclaw --json jobs install-bookmarks-launchd \
  --program /opt/homebrew/bin/birdclaw \
  --env-file ~/.config/bird/env.sh
```

--------------------------------

### Import Twitter/X Archive

Source: https://github.com/steipete/birdclaw/blob/main/docs/archive.md

Initiates the import of a Twitter/X archive into SQLite. Specify the archive path or let autodiscovery find it. Use `--json` for JSON output.

```bash
birdclaw import archive --json
```

```bash
birdclaw import archive ~/Downloads/twitter-archive-2025.zip --json
```

--------------------------------

### Sync Local SQLite with Remote Backup Repository

Source: https://github.com/steipete/birdclaw/blob/main/docs/backup.md

The `backup sync` command provides a recommended round-trip workflow. It clones/configures the backup repo, pulls remote changes, merges remote backup rows into local SQLite, exports the union back to shards, and commits/pushes the backup repo. Use `--json` for JSON output.

```bash
birdclaw backup sync \
  --repo ~/Projects/backup-birdclaw \
  --remote https://github.com/steipete/backup-birdclaw.git \
  --json
```

--------------------------------

### Run Project Tests and Builds

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Execute various testing, coverage, build, and end-to-end tests using pnpm. The performance testing command allows for specific scenario and iteration configuration.

```bash
pnpm check
pnpm test
pnpm coverage
pnpm build
pnpm e2e
pnpm perf:browser -- --scenario=links,links-toggle --iterations=5
```

--------------------------------

### Dry-Run Follower and Following Sync

Source: https://github.com/steipete/birdclaw/blob/main/docs/follow-graph.md

Performs a dry-run of the follower and following sync commands to preview actions without making live requests. This is useful for understanding cache status, page sizes, and potential X requests.

```bash
birdclaw sync followers --json
birdclaw sync following --json
```

--------------------------------

### Follow Graph Queries

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Perform follow graph queries including syncing followers/following, summarizing the graph, and retrieving events or top followers. These commands are cache-first and default to dry-run. Use `--yes` to bypass dry-run.

```bash
pnpm cli sync followers --json
```

```bash
pnpm cli sync following --json
```

```bash
pnpm cli sync followers --yes --json
```

```bash
pnpm cli sync following --yes --json
```

```bash
pnpm cli graph summary --json
```

```bash
pnpm cli graph events --since 2026-05-01 --json
```

```bash
pnpm cli graph top-followers --limit 20 --json
```

```bash
pnpm cli graph unfollowed --date 2026-05-01 --json
```

```bash
pnpm cli graph non-mutual-following --sort followers --limit 100 --json
```

```bash
pnpm cli graph mutuals --json
```

--------------------------------

### Initialize Local Birdclaw State

Source: https://github.com/steipete/birdclaw/blob/main/docs/quickstart.md

Initializes the local birdclaw environment, checks authentication status, and displays database statistics. This step creates necessary configuration files and directories.

```bash
birdclaw init
birdclaw auth status --json
birdclaw db stats --json
```

--------------------------------

### Sync All Data

Source: https://github.com/steipete/birdclaw/blob/main/docs/sync.md

Runs all individual sync commands in a predefined order. It is resumable and rate-limit-aware, persisting cursors on interruption.

```bash
birdclaw sync all --transport xurl
```

```bash
birdclaw sync all --transport auto
```

--------------------------------

### Export SQLite Store to JSONL Shards

Source: https://github.com/steipete/birdclaw/blob/main/docs/backup.md

Use `backup export` to write text shards to a local directory. The manifest is validated by default. The `--json` flag outputs JSON, while `--commit` and `--push` enable Git integration.

```bash
birdclaw backup export --repo ~/Projects/birdclaw-store --json
```

```bash
birdclaw backup export --repo ~/Projects/birdclaw-store --commit --push
```

--------------------------------

### List Blocks

Source: https://context7.com/steipete/birdclaw/llms.txt

List existing blocks for a specified account. The command records locally first and attempts live transport reconciliation.

```bash
birdclaw blocks list --account acct_primary --json
```

--------------------------------

### Show AI-ranked actionable queue

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Display the AI-ranked actionable queue for mentions, DMs, or a mix. Supports filtering by kind, score, and replied/unreplied status.

```bash
birdclaw inbox --kind mentions --unreplied --score --limit 20
```

--------------------------------

### Agent Graph Query Commands

Source: https://github.com/steipete/birdclaw/blob/main/docs/follow-graph.md

Provides commands for querying the local follow graph data after at least one complete follower and following snapshot has been synced. These commands are cache-only and do not consume live X reads.

```bash
birdclaw graph summary --json
```

```bash
birdclaw graph events --since 2026-05-01 --json
```

```bash
birdclaw graph top-followers --limit 20 --json
```

```bash
birdclaw graph non-mutual-following --sort followers --limit 100 --json
```

```bash
birdclaw graph mutuals --json
```

```bash
birdclaw graph unfollowed --date 2026-05-01 --json
```

--------------------------------

### Basic Research Command Usage

Source: https://github.com/steipete/birdclaw/blob/main/docs/research.md

Use these commands to initiate the research process. Specify a query or account, and optionally set limits for results and thread depth. The `--json` flag outputs a JSON envelope instead of markdown.

```bash
birdclaw research "codex" --limit 20 --thread-depth 10 --json
```

```bash
birdclaw research --account acct_primary --out ~/research/codex.md
```

--------------------------------

### Import Backup into Birdclaw Home

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Merge a backup from a specified directory into the current Birdclaw home directory. The `--json` flag ensures JSON output.

```bash
birdclaw backup import ~/Projects/backup-birdclaw --json
```

--------------------------------

### View Bookmark Sync Audit Log

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Displays the last 20 lines of the bookmark sync audit log using `tail` and `jq` for JSON parsing.

```bash
tail -n 20 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
```

--------------------------------

### Sync Bookmarks

Source: https://github.com/steipete/birdclaw/blob/main/docs/sync.md

Mirrors Bookmarks. Similar to syncing likes, use `--mode auto` or `--mode bird` and `--refresh` to bypass the cache. `--all` and `--max-pages` control pagination.

```bash
birdclaw sync bookmarks --mode auto --limit 100 --refresh --json
```

```bash
birdclaw sync bookmarks --mode bird --all --max-pages 5 --limit 100 --refresh --json
```

--------------------------------

### Sync Bookmarks with Auto Mode

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Synchronizes bookmarks using the auto transport mode, fetching up to 100 items and refreshing the cache. Includes JSON output.

```bash
birdclaw sync bookmarks --mode auto --limit 100 --refresh --json
```

--------------------------------

### Birdclaw Backup Sync Command

Source: https://github.com/steipete/birdclaw/blob/main/docs/cli.md

Synchronizes the local archive with a remote backup repository. Clones the repo if needed, pulls before reading, and merges remote changes.

```bash
birdclaw backup sync --repo ~/Projects/backup-birdclaw --remote https://github.com/steipete/backup-birdclaw.git --json
```

--------------------------------

### Import DM Archive

Source: https://context7.com/steipete/birdclaw/llms.txt

Import DM conversations from a local archive file. Choose between importing full message bodies or just metadata.

```bash
birdclaw import archive ~/Downloads/archive.zip --dm-mode full --json
```

```bash
birdclaw import archive ~/Downloads/archive.zip --dm-mode metadata --json
```

--------------------------------

### Package Layout

Source: https://github.com/steipete/birdclaw/blob/main/docs/data-architecture.md

Illustrates the directory structure and organization of the birdclaw project packages.

```text
birdclaw/
  apps/
    web/
  packages/
    archive/
    cli/
    core/
    db/
    server/
    transport-bird/
    transport-official/
    transport-xurl/
    transport-xweb/
    ui/
  docs/
    spec.md
    cli.md
    data-architecture.md
```

--------------------------------

### Blocklist Management

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Commands for managing a blocklist, including listing, syncing, importing from a file, adding, recording, removing accounts, and banning/unbanning users. The `--account` flag specifies the account to operate on, and `--json` provides JSON output.

```bash
pnpm cli blocks list --account acct_primary --json
```

```bash
pnpm cli blocks sync --account acct_primary --json
```

```bash
pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
```

```bash
pnpm cli blocks add @amelia --account acct_primary --json
```

```bash
pnpm cli blocks record @amelia --account acct_primary --json
```

```bash
pnpm cli blocks remove @amelia --account acct_primary --json
```

```bash
pnpm cli ban @amelia --account acct_primary --transport auto --json
```

```bash
pnpm cli unban @amelia --account acct_primary --transport bird --json
```

--------------------------------

### Capped Refresh for Followers and Following

Source: https://github.com/steipete/birdclaw/blob/main/docs/follow-graph.md

Performs a capped refresh of follower and following data, limiting the number of pages fetched. Use `--allow-partial` to acknowledge incomplete snapshots, which are not used for churn events.

```bash
birdclaw sync followers --yes --max-pages 1 --allow-partial --json
birdclaw sync following --yes --max-pages 1 --allow-partial --json
```

--------------------------------

### First Moderation Pass Commands

Source: https://github.com/steipete/birdclaw/blob/main/README.md

Perform initial moderation tasks including exporting mentions, fetching replies for a specific account, and importing a blocklist.

```bash
pnpm cli mentions export --mode xurl --refresh --all --max-pages 9 --limit 100
```

```bash
pnpm cli profiles replies @borderline_handle --limit 12 --json
```

```bash
pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
```

--------------------------------

### Import with Metadata-Only DMs

Source: https://github.com/steipete/birdclaw/blob/main/docs/archive.md

Import the archive while skipping direct message bodies for faster processing by setting `--dm-mode` to `metadata`.

```bash
birdclaw import archive ~/Downloads/twitter-archive.zip --dm-mode metadata --json
```

--------------------------------

### Ban and Unban Accounts

Source: https://github.com/steipete/birdclaw/blob/main/docs/moderation.md

Shorthand commands for adding or removing block entries, with an additional `--transport` option to specify the live transport method. `auto` is the default and includes a cookie-backed fallback.

```bash
birdclaw ban @amelia --account acct_primary --transport auto --json
```

```bash
birdclaw unban @amelia --account acct_primary --transport bird --json
```

--------------------------------

### Import JSONL Shards into Local SQLite

Source: https://github.com/steipete/birdclaw/blob/main/docs/backup.md

Use `backup import` to merge rows from JSONL shards into your local SQLite store. It validates the backup by default unless `--no-validate` is used. The `--replace` flag restores exactly from backup, deleting local portable rows first.

```bash
birdclaw backup import ~/Projects/birdclaw-store --json
```

--------------------------------

### Dry Run Archive Import

Source: https://github.com/steipete/birdclaw/blob/main/docs/archive.md

Perform a dry run of the archive import to analyze the data without writing any changes to the database. Use `--json` for structured output.

```bash
birdclaw import archive ~/Downloads/twitter-archive.zip --dry-run --json
```