Command-line tool

bsbot manages your bots and their name.bluesky.bot handles from a terminal: the same actions as the dashboard, for scripts and for people who live in a shell. It runs on macOS and Linux with Node.js 22 or later.

bash

npm install --global @blueskydotbot/cli
bsbot login

The npm package is @blueskydotbot/cli and the command it installs is bsbot. To run it without installing, use npx @blueskydotbot/cli login (or pnpm dlx @blueskydotbot/cli, yarn dlx @blueskydotbot/cli, bunx @blueskydotbot/cli).

The package is not on npm yet. Until it is, run it from a checkout of the project: node packages/cli/src/bin.ts <command> (Node.js 24).

bsbot login opens bluesky.bot in your browser. Sign in with Bluesky as usual (no password ever goes through the terminal), check the machine name the page shows, and choose Authorize. The browser hands a one-time code back to the CLI on your own machine, and the CLI saves its token.

The token lasts 30 days. Then run login again.
It is saved in ~/.config/bsbot/credentials.json (or $XDG_CONFIG_HOME/bsbot/), readable by you only. It is never printed, not even with --json.
It can only manage your bots' handles. It cannot post, follow, read your Bluesky account, change your settings or delete your account.
--name <label> names the machine in your settings (its host name by default), e.g. bsbot login --name "CI".
On a machine without a browser, add --no-browser and open the printed link elsewhere; the browser must be able to reach the CLI's machine, for instance through ssh -L.

To stop: bsbot logout revokes the token. You can also revoke any machine under Settings → CLI access in the dashboard, and Sign out everywhere revokes every token at once.

Commands

Command	What it does
`whoami`	The account you are signed in as, and when the token expires
`bots`	Your bots, their handle, and whether it is live
`check <name>`	Whether `<name>.bluesky.bot` is free (no sign-in needed)
`claim <bot> <name>`	Claims `<name>.bluesky.bot` for a bot and switches the bot to it
`switch <bot>`	Asks the bot's server again to use its handle
`verify <bot>`	Checks that the handle is live on Bluesky
`release <bot>`	Gives the handle up; asks first, or add `--yes`
`directory`	Browses the public directory: `--q`, `--category`, `--verified`, `--limit`, `--cursor`

<bot> is a bot's DID, its handle, its previous handle (before it got a .bluesky.bot one), or just the name: weather for weather.bluesky.bot. New bots are added from the dashboard: it takes a sign-in on the bot account itself.

bash

bsbot check weather
bsbot claim weather.bsky.social weather
bsbot verify weather

The rules are the dashboard's: names of 3 to 30 characters, reserved names, a short grace period on released handles, and the same limit on handle changes per hour, shared between the dashboard and the CLI.

Scripts

Every command takes --json: the answer of the API on stdout, and {"error": {"code", "message"}} on stderr when it fails. The exit code is 0 on success, 1 on an error, 2 on a usage mistake.

bash

bsbot bots --json | jq -r '.bots[] | select(.verifiedAt == null) | .did'

Under the hood, the CLI calls the /me/* routes of the API with its token (Authorization: Bearer). They are listed in the API reference.