A simple tool which lets you scrape twitter accounts and crosspost them to bluesky accounts! Comes with a CLI and a webapp for managing profiles! Works with images/videos/link embeds/threads.
···11-# ๐ฆ Tweets-2-Bsky
11+# Tweets-2-Bsky
2233-> **Note**: This project is built on top of [**bird**](https://github.com/steipete/bird) by [@steipete](https://github.com/steipete), which provides the core Twitter interaction capabilities.
33+A powerful tool to crosspost Tweets to Bluesky, supporting threads, videos, and high-quality images.
4455-A powerful tool to crosspost your Tweets to Bluesky automatically. Now features a **Web Dashboard** for easy management, **Multi-account support** for different owners, and **Custom PDS** hosting support.
55+## Features
6677-## โจ Features
77+- ๐ **Crossposting**: Automatically mirrors your Tweets to Bluesky.
88+- ๐งต **Thread Support**: INTELLIGENTLY handles threads, posting them as Bluesky threads.
99+- ๐น **Video & GIF Support**: Downloads and uploads videos/GIFs natively to Bluesky (not just links!).
1010+- ๐ผ๏ธ **High-Quality Images**: Fetches the highest resolution images available.
1111+- ๐ **Smart Link Expansion**: Resolves `t.co` links to their original URLs.
1212+- ๐ฅ **Multiple Source Accounts**: Map multiple Twitter accounts to a single Bluesky profile.
1313+- โ๏ธ **Web Dashboard**: Manage accounts, view status, and trigger runs via a modern UI.
1414+- ๐ ๏ธ **CLI & Web Support**: Use the command line or the web interface.
81599-- **Web Dashboard**: Modern interface to manage all your sync tasks.
1010-- **Multi-User Mapping**: Let others add their accounts (e.g., Dan, Josh) with their own owners.
1111-- **Multi-Account Support**: Sync Twitter A -> Bluesky A, Twitter B -> Bluesky B, etc.
1212-- **Tailscale Ready**: Accessible over your local network or VPN.
1313-- **Interactive CLI**: Manage everything from the terminal with `./crosspost`.
1414-- **High Quality**: Supports threads, high-quality images, and videos.
1616+## Quick Start
1717+1818+1. **Clone the repository:**
1919+ ```bash
2020+ git clone https://github.com/yourusername/tweets-2-bsky.git
2121+ cd tweets-2-bsky
2222+ ```
2323+2424+2. **Install dependencies:**
2525+ ```bash
2626+ npm install
2727+ ```
2828+2929+3. **Build the project:**
3030+ ```bash
3131+ npm run build
3232+ ```
15331616----
3434+4. **Start the server:**
3535+ ```bash
3636+ npm start
3737+ ```
3838+ Access the dashboard at `http://localhost:3000`.
17391818-## ๐ Quick Start
4040+## Updating
19412020-### 1. Prerequisites
2121-- **Node.js** installed.
2222-- A Twitter account (burner recommended) for global cookies.
2323-- Bluesky account(s) with **App Passwords**.
4242+To update to the latest version without losing your configuration:
24432525-### 2. Installation
2644```bash
2727-git clone https://github.com/j4ckxyz/tweets-2-bsky.git
2828-cd tweets-2-bsky
2929-npm install
3030-npm run build
4545+./update.sh
3146```
32473333-### 3. Start Syncing & Web UI
3434-```bash
3535-# This starts both the sync daemon AND the web dashboard
3636-npm start
4848+This script will pull the latest code, install dependencies, and rebuild the project. **Restart your application** after running the update.
4949+5050+## Configuration & Security
5151+5252+### Environment Variables
5353+5454+Create a `.env` file for security (optional but recommended):
5555+5656+```env
5757+PORT=3000
5858+JWT_SECRET=your-super-secret-key-change-this
3759```
3838-By default, the web interface runs at **http://localhost:3000**. If you are using Tailscale, it's accessible at `http://your-tailscale-ip:3000`.
39604040-### 4. Setup (Web Dashboard)
4141-1. Open the dashboard in your browser.
4242-2. **Register** a new account (email/password).
4343-3. Log in and go to **Global Twitter Config** to enter your cookies.
4444-4. Use **Add New Mapping** to connect a Twitter handle to a Bluesky account.
6161+> **โ ๏ธ Security Note:** If you do not set `JWT_SECRET`, a fallback secret is used. For production or public-facing deployments, **YOU MUST SET A STRONG SECRET**.
45624646----
6363+### Data Storage
47644848-## ๐ Advanced Usage
6565+- **`config.json`**: Stores your account mappings and encrypted web user passwords. Note that Bluesky app passwords are stored in plain text here to facilitate automated login. **Do not share this file.**
6666+- **`data/database.sqlite`**: Stores the history of processed tweets to prevent duplicates.
49675050-### Disable Web Interface
5151-If you only want to run the sync daemon without the web UI:
5252-```bash
5353-npm start -- --no-web
5454-```
6868+## Usage
55695656-### Command Line Interface (CLI)
5757-You can still manage everything via the terminal:
5858-```bash
5959-# Set Twitter cookies
6060-./crosspost setup-twitter
7070+### Web Interface
61716262-# Add a mapping
6363-./crosspost add-mapping
7272+1. Register your first account (this user becomes the **Admin**).
7373+2. Go to settings to configure your Twitter Auth Token and CT0 (cookies).
7474+3. Add mappings:
7575+ * Enter one or more **Twitter Usernames** (comma-separated).
7676+ * Enter your **Bluesky Handle** and **App Password**.
7777+4. The system will check for new tweets every 5 minutes (configurable).
64786565-# List/Remove
6666-./crosspost list
6767-./crosspost remove
6868-```
7979+### CLI
8080+8181+- **Add Mapping**: `npm run cli add-mapping`
8282+- **Edit Mapping**: `npm run cli edit-mapping`
8383+- **Import History**: `npm run cli import-history`
8484+- **List Accounts**: `npm run cli list`
69857070-### Backfilling Old Tweets
7171-```bash
7272-# Example: Import the last 20 tweets for a user
7373-npm run import -- --username YOUR_TWITTER_HANDLE --limit 20
7474-```
8686+## Twitter Cookies (Auth)
75877676----
8888+You need your Twitter `auth_token` and `ct0` cookies.
8989+1. Log in to Twitter/X in your browser.
9090+2. Open Developer Tools (F12) -> Application -> Cookies.
9191+3. Copy the values for `auth_token` and `ct0`.
77927878-## โ๏ธ How to get Twitter Cookies
7979-1. Log in to Twitter in your browser.
8080-2. Open **Developer Tools** (F12) -> **Application** tab -> **Cookies**.
8181-3. Copy `auth_token` and `ct0` values.
9393+## License
82948383-## โ๏ธ License
8484-MIT
9595+MIT