KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

bluesky-account-migrator

★ 28 Open GitHub ↗

A simple CLI for migrating Bluesky accounts from one PDS to another.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bluesky-account-migrator

A Node.js CLI for migrating Bluesky accounts from one PDS to another.

> [!WARNING]
> This is community-maintained software. It has no affiliation with Bluesky the company.
> Use at your own risk.
>
> `bluesky-account-migrator` is currently in a beta state. If a migration fails, you will
> have to figure out how to recover on your own. See [troubleshooting](#troubleshooting)
> for more details.

## Installation

```text
# In a package
npm install bluesky-account-migrator

# Globally
npm install -g bluesky-account-migrator
```

Or the equivalent incantation using your package manager of choice.

## Usage

Migrating your Bluesky account is a potentially destructive operation that can result in
losing access to the account. This CLI files away some of the rough edges, but it's far
from perfect, and can't help you recover if the migration fails (although you may be able
to do so yourself, see [troubleshooting](#troubleshooting)).

To get a better understanding of the risks and steps involved in account migration, see
[Bluesky's account migration guide](https://github.com/bluesky-social/pds/blob/9ac9461ce2e4ed7ac66889bb1017662a2f846c98/ACCOUNT_MIGRATION.md). The implementation
of this package is based on the snippet in that guide.

### Requirements

- A `did:plc` Bluesky account
  - If you don't know what kind of account you have, you should be good to go.
- A PDS to migrate to
  - Ideally, this PDS has SMTP enabled in order to verify your email.
    Bluesky the app will ask you to do this for the new account.
  - See [Confirming your email](#confirming-your-email) for a potential way
    around SMTP.
- Two-factor authentication (2FA) disabled on your Bluesky account.
  - This is only required for the duration of the migration.

### Gotchas

#### Custom handles

A "custom" handle is a handle that is not a subdomain of the PDS URL. For example,
for a account hosted on `bsky.social`, `foo.bsky.social` would be a "normal" handle,
whereas `foo.bar` would be a custom handle.

Bluesky's PDS implementation currently does not support creating new accounts with
custom handles. However, the handle can be updated after migration. If you submit
a custom handle as your new handle, the CLI will perform this update at the end
of the migration, after activating the new account on the new PDS.

For further deatils, see e.g.
[this discussion](https://github.com/bluesky-social/atproto/discussions/2909)
and
[this issue](https://github.com/bluesky-social/pds/issues/110#issuecomment-2439866348).

If you are using [the `pipe` command](#pipe), you will need to provide the temporary and final
handles in the passed-in credentials, for example:

```json5
{
  "credentials": {
    // The other credentials as normal
    // ...
    "newHandle": {
      "temporaryHandle": "new-temp.pds.com"
      "finalHandle": "foo.com",
    },
  }
}
```

#### Confirming your email

Even though you probably already confirmed your email on the old PDS, Bluesky will want you
to confirm your email on the new PDS as well. (There's not really a point to this, but this is
how it works.)

To do this, you can either configure SMTP on your PDS, _or_ copypaste
[this script](https://github.com/rekmarks/bluesky-account-migrator/blob/main/scripts/pds-confirm-email.sh)
to your PDS and run it with the DID of your migrated account.

### CLI

The CLI has a single command `migrate`, which you can run using e.g. `npx`:

```text
npx bluesky-account-migrator migrate [--mode <mode>]
```

The CLI has two modes.

#### `interactive`

This will interactively walk you through migrating your Bluesky account from one PDS to
another. It will collect most of the necessary information upfront, such as the PDS URLs,
account handles, etc., then ask if you want to start the migration:

```text
? Perform the migration with these credentials? (Y/n)
```

Migrating your account requires completing an email challenge. Assuming all goes well,
the migration will run until the challenge email has been sent. You will have to retrieve
the confirmation token in this email and provide it to the CLI to complete the migration:

```text
An email should have been sent to the old account's email address.

? Enter the confirmation token from the challenge email
```

If the challenge token is correct, the migration should complete successfully.
At the end of the migration, the private recovery key will be printed to the terminal.
You must save this key in a secure location, or you could lose access to your account.

#### `pipe`

This causes the CLI to read from `stdin` and write to `stdout`. It will only output
the results of running the migraiton to `stdout`, and any errors or other logs will
be written to `stderr`.

Given a file `credentials.json` with the following contents:

```json
{
  "credentials": {
    "oldPdsUrl": "https://bsky.social",
    "newPdsUrl": "https://pds.com",
    "oldHandle": "old.handle",
    "oldPassword": "oldpass123",
    "newHandle": { "handle": "new.pds.com" },
    "newEmail": "new@email.com",
    "newPassword": "newpass123",
    "inviteCode": "invite-123"
  }
}
```

The CLI can then be invoked as follows:

```bash
cat credentials.json | npx bluesky-account-migrator --mode pipe > result.json
```

If the credentials are correct, `result.json` should look like this:

```json
{
  "state": "RequestedPlcOperation",
  "credentials": {
    "oldPdsUrl": "https://bsky.social",
    "newPdsUrl": "https://pds.com",
    "oldHandle": "old.handle",
    "oldPassword": "oldpass123",
    "newHandle": { "handle": "new.pds.com" },
    "newEmail": "new@email.com",
    "newPassword": "newpass123",
    "inviteCode": "invite-123"
  }
}
```

In this state, the migration should have dispatched a challenge email to the email
associated with the account on the old PDS. Once you have retrieved the confirmation
token from the email, you can complete the migration like so:

```bash
cat result.json | \
  jq '. + {"confirmationToken": "<Token>"}' | \
  npx bluesky-account-migrator migrate --mode pipe > \
  finalResult.json
```

If the confirmation token is correct, `finalResult.json` should look like this:

```json
{
  "state": "Finalized",
  "credentials": {
    "oldPdsUrl": "https://bsky.social",
    "newPdsUrl": "https://pds.com",
    "oldHandle": "old.handle",
    "oldPassword": "oldpass123",
    "newHandle": { "handle": "new.pds.com" },
    "newEmail": "new@email.com",
    "newPassword": "newpass123",
    "inviteCode": "invite-123"
  },
  "confirmationToken": "<Token>",
  "newPrivateKey": "<PrivateKey>"
}
```

> [!IMPORTANT]
> If the migration fails the CLI will exit with a non-zero error code, but the result
> will still be written to `stdout`. This enables retrieving the generated private key,
> if any.
>
> To retrieve the migration output, you **must** ensure that your script handles failures
> appropriately. For example, you cannot naively use `set -e` in Bash, since that would
> prevent capturing the output on failure.
> Instead, capture the output and check the exit code separately:
>
> ```bash
> output=$(cat result.json | npx bluesky-account-migrator migrate --mode pipe)
> exit_code=$?
>
> if [ $exit_code -ne 0 ]; then
>   echo "Migration failed with exit code $exit_code" >&2
>   echo "Output was:" >&2
>   echo "$output" >&2
>   exit $exit_code
> fi
>
> echo "$output" > finalResult.json
> ```

### API

The migration is implemented as a state machine in the form of the `Migration` class.
You can run a migration programmatically as follows:

```ts
import { Migration, MigrationState } from 'bluesky-account-migrator';

const credentials = {
  oldPdsUrl: 'https://bsky.social',
  oldHandle: 'old.handle',
  oldPassword: 'oldpass123',
  inviteCode: 'invite-123',
  newPdsUrl: 'https://pds.com',
  newHandle: { handle: 'new.pds.com' },
  newEmail: 'new@email.com',
  newPassword: 'newpass123',
};

const migration = new Migration({ credentials });

let result = await migration.run();
if (result !== 'RequestedPlcOperation') {
  // Something has gone extremely wrong if this happens
  throw new Error('unexpected migration state');
}

// You have to get this from the challenge email and make it available
// to your program somehow
const confirmationToken = '...';
migration.confirmationToken = confirmationToken;

result = await migration.run();
if (result !== 'Finalized') {
  // Again, something has gone extremely wrong if this happens
  throw new Error('unexpected migration state');
}

// This is the recovery private key for the account, which must be stored
// somewhere or risk the loss of the account
storeSomewhereSafe(migration.newPrivateKey);
```

If you need to persist an unfinished migration, e.g. on failure or when getting
the confirmation token, you can use the `serialize()`/`deserialize()` methods:

```ts
const migration = new Migration({ credentials });
await migration.run();

// NOTE: This will output the user's passwords and private key in plaintext,
// if present.
const serialized = migration.serialize();
saveMigration(JSON.stringify(serialized, null, 2));

// Later
const savedMigration = loadMigration();
const migration = Migration.deserialize(JSON.parse(savedMigration));
migration.confirmationToken = confirmationToken;
await migration.run();
```

### Troubleshooting

> [!IMPORTANT]
> If you encounter any problems with `bluesky-account-migrator`, please
> [file an issue](https://github.com/rekmarks/bluesky-account-migrator/issues/new).

#### Migration failure

If your migration fails, you are alone in strange territory. However, all is not lost.
While `bluesky-account-migrator` is not (yet) equipped to resume partial migrations,
the error should tell you where it failed. In addition, the migration is implemented
as a state machine, and you should be able to figure out what's left to do by consulting
[this file](./src/migration/Migration.ts). In brief, each state maps to an "operation",
which is essentially a function wrapping a set of logically associated API calls. By
identifying the error and the remaining API calls, you can likely compose a script that
completes the rest of the migration.

#### Other issues

- Missing data / blobs
  - It may be the case that your migrated account is missing data / blobs.
  - You can verify this manually using `com.atproto.server.checkAccountStatus`.
  - Finding missing data is currently out of scope for this CLI.

bluesky-account-migrator

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README