Manage your Bluesky bots and their name.bluesky.bot handles from the
terminal: sign in with Bluesky, then claim, switch, verify and release handles.
No dependencies, Node.js 22+.
Signing in happens in your browser, so no password ever goes through the terminal. You can also run your bots' checkup, edit their directory listing (from a CI job too), browse the directory of Bluesky.bot and run its free tools.
npm install --global @blueskydotbot/cli
bsbot login
bsbot check weather
bsbot claim weather.bsky.social weather
bsbot verify weather
bsbot doctor weather
The npm package is
@blueskydotbot/cli; the
command it installs is bsbot. Install it once:
npm install --global @blueskydotbot/cli
bsbot --help
Or run it without installing, with npx @blueskydotbot/cli <command> (for
example npx @blueskydotbot/cli login). Other package managers work too:
pnpm dlx @blueskydotbot/cli, yarn dlx @blueskydotbot/cli or
bunx @blueskydotbot/cli.
Requirements: macOS or Linux, Node.js 22 or later. No dependency.
This README describes the 0.2.0 release source. Listing, checkup, init and
tool commands were added after npm version 0.1.0; source version 0.1.1
was never published. Preparing or packing this source does not publish it.
Check npm view @blueskydotbot/cli dist-tags and your installed bsbot --help
for availability. The server support must be deployed before a CLI version
using it is published; see RELEASING.md.
| Command | What it does |
|---|---|
login |
Signs in through the browser (--no-browser, --name <label>) |
logout |
Revokes this machine's token and forgets it |
whoami |
The account you are signed in as, and what the token may do |
bots |
Your bots, their handle, and whether it is live |
doctor [<bot>] |
The bot's checkup: what to fix in its disclosure and setup (every bot without <bot>; --strict, --verbose) |
listing get <bot> |
The bot's directory listing |
listing set <bot> |
Changes the listing from flags or --file (see below) |
init [dir] |
Creates a local TypeScript or Python bot starter (see below) |
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) |
tool [<slug> key=value ...] |
Lists the free tools, or runs one |
<bot> is a bot's DID, its handle, its previous handle, or the name of its
.bluesky.bot handle. Every command takes --json for scripts; the exit code
is 0 on success, 1 on an error and 2 on a usage mistake, plus 3 when
doctor finds a check to fix (or a suggestion, with --strict). Errors print
the server's message; with --json they are
{ "error": { "code", "message" } } on stderr, plus field and reason for a
refused listing field, parameter for a refused parameter and scope for a
token that lacks one. Run bsbot --help for the details, and see
https://bluesky.bot/docs/cli.
bsbot doctor weather # one bot, every check with a link to fix it
bsbot doctor --verbose # every bot, one line each, then the checks
bsbot doctor weather --strict # exit code 3 on a suggestion too
--json prints the server's document as is ({ "bots": [ … ] } for every
bot). Each checkup reads the bot's Bluesky profile, so the server allows 120
an hour; checking every bot waits out a short Retry-After and stops,
naming the bots left, when the wait would be over a minute.
Deploy tokens accept a DID or a full handle; a full handle is resolved through
the public API without sending the token. They never enumerate your bots. CLI
tokens retain the short-name and previous-handle forms. whoami shows the token
type, scopes and bound bot when the server reports them.
listing set reads the listing first and sends only the fields that differ,
or nothing ("No change", exit code 0): each change counts against a limit
of 30 an hour, shared with the dashboard.
bsbot listing set weather --listed --category weather --languages fr,en \
--description "Hourly weather for Paris." --operator-name "Météo Lab"
bsbot listing set weather --file listing.json --dry-run
| Flag | Field |
|---|---|
--listed [true|false], --unlisted |
listed (bare --listed means true) |
--category <slug>, --category none |
category (none clears it) |
--description <text>, --no-description |
description |
--languages <code,code> |
languages, the main one first |
--recent-posts, --no-recent-posts |
showRecentPosts |
--operator <text>, --no-operator |
operator.name |
--show-operator, --hide-operator |
operator.shown |
--source-url <url> |
sourceUrl |
--open-source, --no-open-source |
openSource |
--support-url <url> |
supportUrl |
The original --operator-name, --operator-shown and --operator-hidden aliases remain supported.
An empty value (--description "") also clears a field. --file takes a JSON
object with any of the fields of the listing, as listing get --json shows
them under listing (usage and disclosure included); the flags win over
the file. An unknown field is refused before anything is sent. The server
checks every value with the dashboard's rules and saves all or nothing; a
refused value prints its field and reason. --dry-run prints the
difference and stops.
Disclosure files can explicitly send contactEmailPublic and
usesGenerativeAi booleans, including false. An e-mail contact needs
contactEmailPublic: true in the same request. The CLI preserves that explicit
consent when replacing a contact, but never invents consent or an AI answer.
An AI-category refusal remains invalid_listing with
field: "disclosure.usesGenerativeAi", reason: "required_for_ai".
A token from before the listing existed cannot read or change it: run
bsbot login again (bsbot whoami shows the token's scopes).
bsbot init my-bot --template python
bsbot init my-bot --template typescript --bot weather.bluesky.bot --yes
bsbot init my-bot --template python --no-git --yes --json
init asks for the language, directory and an optional bot when omitted.
--yes skips questions, defaulting to TypeScript and my-bluesky-bot.
It refuses a populated or symlink destination, including with --yes.
It copies bundled files without downloading or installing anything, then runs
git init and a first commit. Your normal Git identity, signing and hooks
apply; --no-git skips those commands. If a commit fails, the generated files
remain for review and a manual commit. --json returns exactly
{ "dir", "template", "files" }.
No account is needed to generate files. An unauthenticated --bot accepts a
full handle without a network request. When signed in, an explicit --bot
reads that bot's private listing; deploy tokens need its DID or full handle.
Interactive mode also offers numbered owned-bot choices when the token
explicitly permits listing handles; deploy and listing-only tokens are never
used to enumerate bots. Leave the choice blank to generate without prefill,
including when the optional lookup is unavailable offline.
No API token or app password is written to generated files. All contact
e-mails and hidden operator names are omitted from the generated listing,
even if the platform can display the e-mail. Omitted properties stay absent
in the partial listing file; syncing it preserves those server values. The
notice names omitted fields without printing their values. Explicit
listing get and listing set --file retain their private API contract.
An empty contact or hidden operator name is omitted too, so the generated
file cannot clear a private value added later. To explicitly clear a field,
edit the listing file yourself or use the corresponding listing option.
The CLI requires Node 22+, while running the generated TypeScript starter
requires Node 24; the Python starter documents its own Python requirements.
Review the starter README, posts.txt, .env.example and listing before
running anything. init only prints repository/secret setup steps: it never
pushes, sets a secret or enables Actions. Workflows in these development
snapshots are manual-only, and posting stays in dry-run mode by default.
The bundled development snapshots are pinned to commits
591e7a4c3e3f2f95f3f3056b998847a5cd25d062 (TypeScript) and
10bc1abd8c0be6981b7c13ce2792a9c46a141792 (Python). They are not published
template releases. The CLI publication gate refuses them until each has a
real immutable public tag whose tree matches the bundle; see
RELEASING.md.
Set BSBOT_TOKEN to a token, as a secret of your CI: commands use it instead
of the saved credentials, and never print it nor write it to disk. Today that
token is the one bsbot login saves (the token field of the credentials
file), valid 30 days. Passing the bot's DID saves a request. With GitHub
Actions:
- run: npx --yes @blueskydotbot/cli listing set did:plc:… --file listing.json
env:
BSBOT_TOKEN: ${{ secrets.BSBOT_TOKEN }}
bsbot tool lists the free tools of Bluesky.bot; bsbot tool <slug> key=value ... runs one and prints its result (--json: the whole answer).
For example bsbot tool did-finder handle=bsky.app. Signed in, it sends your
token, which raises the limits tenfold; signed out, it works anonymously. See
https://bluesky.bot/docs/tools-api for each tool's parameters.
Found a bug or missing a command? Open an issue at
https://github.com/blueskydotbot/cli/issues with the version
(bsbot --version), the command and what it printed. Never paste your token.
BSBOT_TOKEN takes precedence over the credentials file. An explicitly empty
or malformed value fails instead of falling back to saved credentials.
- The token is saved in
~/.config/bsbot/credentials.json(or$XDG_CONFIG_HOME/bsbot/, or$BSBOT_CONFIG_DIR), readable by you only. It lasts 30 days and is never printed, not even with--json. - It can only manage your bots' handles, run their checkup and edit their directory listing: it cannot post, follow, read your Bluesky account or change your settings.
bsbot logoutrevokes it; so does Settings → CLI access on bluesky.bot. A token given inBSBOT_TOKENis not revoked bybsbot logout: revoke it in the settings.
Report vulnerabilities privately: see SECURITY.md.
npm ci
npm test
npm run build
node dist/bin.js --help
Node.js 24 can also run the TypeScript sources directly:
node src/bin.ts --help.
--api-url <url> (or BSBOT_API_URL) points the CLI at another server; plain
http is only accepted for localhost, 127.0.0.1 and [::1]. When you
try a change against a local development server of bluesky.bot, keep its
credentials apart from your real ones:
export BSBOT_CONFIG_DIR="$(mktemp -d)"
node dist/bin.js check weather --api-url http://localhost:3000
node dist/bin.js login --api-url http://localhost:3000
Credentials are bound to the server that issued them: switching servers needs
a new login.
Bug reports and ideas are welcome in
GitHub issues. For a pull
request, open an issue first for anything larger than a small fix, keep the
CLI free of runtime dependencies, add tests, and add a line to the
[Unreleased] section of CHANGELOG.md. npm test and
npm run build must pass.
Each stable version gets a GitHub Release with its changelog, and is announced on Bluesky by @cli.bluesky.bot: follow it to hear about new versions. Maintainers release as described in RELEASING.md.