Skip to content
blueskydotbotPublic

About

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+.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

cli.bluesky.bot on Bluesky.bot

bsbot

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

Install

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.

Release source

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.

Usage

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.

The checkup

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.

The listing

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).

Start a bot

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.

In CI

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 }}

The tools

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.

Bugs and ideas

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.

Security

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 logout revokes it; so does Settings → CLI access on bluesky.bot. A token given in BSBOT_TOKEN is not revoked by bsbot logout: revoke it in the settings.

Report vulnerabilities privately: see SECURITY.md.

Development

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.

Contributing

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.

License

MIT

About

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+.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages