Birdclaw

https://github.com/steipete/birdclaw
Admin
Birdclaw is a local-first Twitter workspace that stores your archives, DMs, likes, and bookmarks in...
Tokens:39,396
Snippets:503
Trust Score:10
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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}'
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### Configure Auto-Sync Backup

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

Enable auto-sync for backups by setting 'autoSync' to true and defining the 'staleAfterSeconds' threshold. This configuration dictates when the system pulls and merges from Git and when a full backup sync is performed after data-changing commands.

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

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

### birdclaw backup

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

Export the canonical SQLite store as deterministic Git-friendly JSONL shards. Supports export, sync, import, and validation.

```APIDOC
## `birdclaw backup`

Export the canonical SQLite store as deterministic Git-friendly JSONL shards. The backup is the durable long-lived record; SQLite is a fast local index built from it.

### Export shards to a local directory
```bash
birdclaw backup export --repo ~/Projects/birdclaw-store --json
```

### Export with Git commit and push
```bash
birdclaw backup export --repo ~/Projects/birdclaw-store --commit --push
```

### Full round-trip sync (pull → merge-import → export → commit → push)
```bash
birdclaw backup sync \
  --repo ~/Projects/backup-birdclaw \
  --remote https://github.com/steipete/backup-birdclaw.git \
  --json
```

### Import from a backup repo (merge, preserves local-only rows)
```bash
birdclaw backup import ~/Projects/backup-birdclaw --json
```

### Restore exactly from backup (deletes local portable rows first)
```bash
birdclaw backup import ~/Projects/backup-birdclaw --replace --json
```

### Validate manifest hashes, byte counts, row counts, JSONL parseability
```bash
birdclaw backup validate ~/Projects/backup-birdclaw --json
```

### Backup shard layout:
```
manifest.json
data/accounts.jsonl
data/profiles.jsonl             (bio, follower counts, profile URL, raw JSON)
data/profile_affiliations.jsonl (X badge/org edges)
data/profile_snapshots.jsonl    (profile-change history)
data/profile_bio_entities.jsonl (extracted @handle, domain, company phrases)
data/tweets/YYYY.jsonl          (sharded by year)
data/tweets/unknown.jsonl       (missing timestamps)
data/collections/likes.jsonl
data/collections/bookmarks.jsonl
data/dms/conversations.jsonl
data/dms/YYYY.jsonl
data/moderation/blocks.jsonl
data/moderation/mutes.jsonl
data/follow_snapshots.jsonl
data/follow_events.jsonl
```
```

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

### Sync Bookmarks with Bird Mode

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

Synchronizes bookmarks specifically using the bird transport mode, fetching all available pages with a limit of 100 items per page and refreshing the cache. Includes JSON output.

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

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

### Sync Chronological Timeline

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

Pulls the chronological Following timeline through `bird`. Use `--limit` to set the page size and `--refresh` to bypass the cache.

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

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

### Export Mentions (Default Mode)

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

Use the default 'birdclaw' mode to retrieve normalized mentions from the local SQLite store. This mode is suitable for agents as it avoids live API calls.

```bash
birdclaw mentions export "agent" --unreplied --limit 10
```

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

### Bulk Block Accounts

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

Imports a blocklist from a file to bulk-block specified accounts. This is useful for managing spam or unwanted accounts.

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

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

### Export Mentions for Agents

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

Export mentions for agents. The default mode returns normalized items. Cached live modes return `xurl`-compatible data. Use `--refresh` to force a live fetch. `--all` walks every retrievable mentions page, and `--max-pages` caps that scan.

```bash
pnpm cli mentions export "agent" --unreplied --limit 10
```

```bash
pnpm cli mentions export --mode bird --limit 20
```

```bash
pnpm cli mentions export --mode bird --refresh --limit 20
```

```bash
pnpm cli mentions export --mode xurl --limit 5
```

```bash
pnpm cli mentions export --mode xurl --refresh --limit 5
```

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

```bash
pnpm cli mentions export "courtesy" --mode xurl --limit 5
```

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

### Pipe search results into jq

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

Demonstrates how to pipe the JSON output of a Birdclaw search command into `jq` for further processing and filtering.

```bash
birdclaw search tweets "sync engine" --limit 10 --json | jq '.items[] | {url, snippet}'
```

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

### Force New Live Fetch for Followers

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

Forces a new live fetch for follower data, bypassing the cache only when necessary. Use the `--refresh` flag to ensure the latest data is retrieved.

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

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

### Research Bookmarks and Generate Markdown Briefs

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

Transforms bookmarked tweets into a markdown brief, expanding threads and extracting links. Use `--out` to specify the output file.

```bash
# Research query across bookmarks, expand threads up to 10 levels deep
birdclaw research "codex" --limit 20 --thread-depth 10 --json
```

```bash
# Write markdown brief to a file
birdclaw research "codex" --account acct_primary --out ~/research/codex.md
```

```bash
# JSON shape: { items: [{tweet, thread, links, handles}], links: [...], handles: [...] }
birdclaw research "local-first" --limit 10 --json | jq '.items[0].thread'
```

```bash
# Pre-populate local store to avoid live calls during research
birdclaw sync bookmarks --mode bird --all --json
```

```bash
birdclaw sync mention-threads --limit 50 --delay-ms 1500 --json
```

```bash
birdclaw research "AI agents" --limit 30 --thread-depth 5 --out ~/research/ai-agents.md
```

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

### Uninstall macOS LaunchAgent

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

Removes the bookmark sync LaunchAgent from the system and deletes its plist file. The audit log and lock file are intentionally kept.

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

```bash
rm ~/Library/LaunchAgents/com.steipete.birdclaw.bookmarks-sync.plist
```

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

### Find and Import Twitter Archive

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

Finds and imports a downloaded Twitter/X archive. It also hydrates user profiles with live metadata. This can be done with an explicit path to the archive.

```bash
birdclaw archive find --json
birdclaw import archive --json
# or with an explicit path:
birdclaw import archive ~/Downloads/twitter-archive-2025.zip --json
birdclaw import hydrate-profiles --json
```

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

### List DMs with Filters

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

List conversations with options to refresh live DMs, filter by reply status, minimum followers, and influence score, and sort by influence. Use `--json` for machine-readable output.

```bash
birdclaw dms list --refresh --limit 10 --json
```

```bash
birdclaw dms list --unreplied --min-followers 500 --min-influence-score 90 --sort influence --json
```

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

### Identity Lookup with Whois

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

Perform identity lookups using `whois` to cluster matching conversations and resolve profiles. Supports context, profile resolution, URL expansion, and fallback options. Use `--json` for output.

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

```bash
birdclaw whois "blacksmith" --context 4 --no-xurl-fallback --json
```

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

### Analyze Follow Graph

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

Perform cache-only analysis of the follow graph. These commands do not interact with external services. Ensure data is synced first.

```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 unfollowed --date 2026-05-01 --json
```

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

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

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

### Find Twitter/X Archives

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

Use this command to discover potential archive ZIP files on your system. It searches common download locations and uses Spotlight on macOS for broader discovery.

```bash
birdclaw archive find --json
```

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

### Restore from Backup

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

Restore the store exactly from a backup repository. This operation will delete local portable rows first.

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

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

### Search profiles with whois

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

Find people or organizations using various criteria and evidence. Query intent affects ranking. Use flags to refine search and output.

```bash
birdclaw whois blacksmith --context 4 --no-xurl-fallback --json
```

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

```bash
birdclaw whois "github guy" --current-affiliation github --exclude-domain-only
```

```bash
birdclaw whois blacksmith --tweets --no-xurl-fallback
```

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

### Backup Sync and Validation Commands

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

Use `backup sync` to pull, merge, export, commit, and push changes to a private Git repo. `backup validate` checks the integrity of the backup. Both commands support JSON output.

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

```bash
pnpm cli backup validate ~/Projects/backup-birdclaw --json
```

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

### Database Vacuum

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

Reclaim space and recompute FTS5 shadow tables in the database. This operation is safe to run when the database is not actively being written to.

```bash
birdclaw db vacuum --json
```

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

### Ban and Unban Accounts

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

Shorthand commands for banning and unbanning accounts with explicit transport specification.

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

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

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

### List Mutes

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

List muted accounts for a specified account.

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

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

### Export Mentions (Bird Mode)

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

Export mentions using the 'bird' mode, which shells out to the local 'bird' CLI. This mode is useful when 'xurl' is rate-limited or for accounts with cookie-backed access. Responses are cached.

```bash
birdclaw mentions export --mode bird --limit 20
```

```bash
birdclaw mentions export --mode bird --refresh --limit 20
```

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

### Compose and Reply

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

Commands for composing new posts, replying to tweets, and sending direct messages. Specify the content and the target tweet or DM ID.

```bash
pnpm cli compose post "Ship local software."
```

```bash
pnpm cli compose reply tweet_004 "On it."
```

```bash
pnpm cli compose dm dm_003 "Send it over."
```

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

### Check Authentication Status

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

Check the current authentication status for live transport using the `auth status` command with JSON output.

```bash
pnpm cli auth status --json
```

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

### List and Sync DM Conversations

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

Commands for listing and syncing direct message conversations. Use --refresh to ensure the latest data from the source. Supports filtering by unreplied messages and minimum follower counts.

```bash
birdclaw dms list --refresh --limit 10 --json
```

```bash
birdclaw dms list --unreplied --min-followers 500 --min-influence-score 90 --sort influence --json
```

```bash
birdclaw dms sync --limit 50 --refresh --json
```

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

### Add and Remove Blocks

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

Add or remove blocks for an account. Handles resolution of handles and attempts live blocking via the auto transport.

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

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

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

### Mute List, Mute, Unmute, and Record Mutes

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

Commands for managing local mute entries. Similar to blocks, these commands interact with live mute writes and local recording. Mutes prefer `bird user --json` for target resolution before falling back to `xurl`.

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

```bash
birdclaw mute @amelia --account acct_primary --transport xurl --json
```

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

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

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

### Sync Likes Feed

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

Mirrors the authenticated user's Likes feed. Use `--mode auto` to try xurl first, or `--mode bird` for direct bird fetches. `--refresh` bypasses the cache for live data.

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

```bash
birdclaw sync likes --mode bird --all --max-pages 5 --refresh --json
```

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

### Inspect Bookmark Sync Audit Log

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

View the last 5 entries of the bookmark sync audit log. The log contains details about each sync run, including timestamps, counts, transport source, and backup results.

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

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

### Validate Backup Integrity

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

Run `backup validate` to check the integrity of your backup. It verifies the manifest, shard existence, byte counts, row counts, SHA hashes, and JSONL row parsing. Exits non-zero on failure, suitable for CI.

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

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

### Hydrate Profiles from Live Twitter

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

Refreshes profile information (bios, follower counts, avatars) by fetching live data from Twitter. This command requires a working transport (e.g., `xurl` or `bird`).

```bash
birdclaw import hydrate-profiles --json
```

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

### List Actionable Items by Kind

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

Filters the inbox to a specific kind of item (mentions, DMs, or mixed). The `mixed` kind is the default and interleaves mentions and DMs while preserving the ranking heuristic. Use `--limit` to control the number of items returned.

```bash
birdclaw inbox --kind mentions --limit 10 --json
```

```bash
birdclaw inbox --kind dms --limit 10 --json
```

```bash
birdclaw inbox --kind mixed --limit 20 --json
```

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

### Repeat Follower Sync with Cache Reuse

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

Repeats a follower sync operation. If the account, page size, and caps remain the same, a fresh cache will be reused, avoiding unnecessary live fetches.

```bash
birdclaw sync followers --yes --json
```
Tokens:
Raw