Bluesky from the terminal: which CLI should you use?
Use bsbot for your Bluesky.bot handles, goat for general AT Protocol work, and a posting client for timelines and posts. Our recorded sessions identify the exact version and whether they used public data or local help.
By The Bluesky.bot team
- Published:
- Updated:
- Reviewed:
Choose by the job
For your bots’ name.bluesky.bot handles, start with bsbot and the CLI reference. For public identity resolution, repository exports, CAR files, PLC history or account migration, consider goat. For a timeline or posting client, consider mattn/bsky or an AT Protocol SDK. These tools have different purposes and permissions.
| Tool and version | Best fit | Authentication and writes | Install and licence | Source and review |
|---|---|---|---|---|
bsbot 0.1.0 TypeScript / Node.js ≥ 22 Released Nov 12, 2026 | Manage your bots’ Bluesky.bot handles; public name checks and directory browsing. It does not post or read a timeline. | Browser OAuth for account actions. Its token permits handle management; it is separate from a Bluesky app password. | npm install --global @blueskydotbot/[email protected]MIT | Versioned source Checked Nov 16, 2026 |
goat 0.2.9 Go Released Nov 6, 2026 | Resolve identities, inspect repositories and CAR files, read PLC history, export data and administer or migrate accounts. | Many reads are public. Account writes use login with an app password; the documented client stores credentials on disk. | go install github.com/bluesky-social/[email protected]MIT / Apache-2.0 | Versioned source Checked Nov 16, 2026 |
mattn/bsky 0.0.82 Go Released Aug 19, 2026 | A Bluesky posting and timeline client, with profile, follow, moderation and other account commands. | Its documented login accepts a handle and password. Use an app password; authenticated commands can change the account. | go install github.com/mattn/[email protected]MIT | Versioned source Checked Nov 16, 2026 |
The comparison describes the checked releases, not unreleased repository code. We ran local help for bsbot and bsky, a public name check with bsbot, and a public DID resolution with goat. We did not run authenticated posting, migration or handle changes.
Install and check the actual version
npm install --global @blueskydotbot/[email protected]
bsbot --version
bsbot --helpThe pinned version matches the capture. Use npx @blueskydotbot/[email protected] --help for a one-off run. Check release notes before choosing a newer version. The documented requirements are Node.js 22 or later on macOS or Linux; this session ran on Linux with Node.js 24.
bsbot 0.1.0 ·
Local command; no account connection · Exit code 0
bsbot --helpbsbot 0.1.0: manage your Bluesky bots and their name.bluesky.bot handles.
Usage: bsbot <command> [options]
Account
login [--no-browser] [--name <label>]
Sign in through the browser (OAuth, no password);
<label> names this machine in your settings
logout Revoke this machine's token and forget it
whoami Show the signed-in account
Handles
check <name> Is <name>.bluesky.bot free to claim?
claim <bot> <name> Claim <name>.bluesky.bot for a bot and switch to it
switch <bot> Ask the bot's server again to use its handle
verify <bot> Check that the bot's handle is live on Bluesky
release <bot> [--yes] Give the handle up (the bot goes back to its old one)
Bots
bots List your bots
directory [--q <text>] [--category <c>] [--verified] [--limit <n>] [--cursor <c>]
Browse the public directory
<bot> is a bot's DID, its handle, its previous handle, or the name of its
.bluesky.bot handle. Add bots from the dashboard: https://bluesky.bot/manage
Options
--json Machine-readable output (never contains the token)
--api-url <url> Another server (or BSBOT_API_URL)
-h, --help This help
-v, --version The version
Start with a public read
check asks whether a name is free. It does not reserve or claim it. The captured name belongs to this project’s CLI account; availability and suggestions may change later.
bsbot 0.1.0 ·
Read-only public Bluesky.bot API · Exit code 0
bsbot check cli --json{
"name": "cli",
"handle": "cli.bluesky.bot",
"available": false,
"reason": "taken",
"suggestions": [
"cli2",
"cli-24",
"cli3"
]
}
Sign in and manage your own bot
The following commands are instructions, not recorded authenticated sessions. Add the bot in the dashboard first. Run bsbot login, verify the account and machine name in the browser, then authorize. No Bluesky password passes through bsbot. Its token is for Bluesky.bot, not for posting to Bluesky.
bsbot login
bsbot whoami
bsbot botsAfter choosing your own bot DID and a free name, the published syntax is:
bsbot claim BOT_DID chosen-name
bsbot switch BOT_DID
bsbot verify BOT_DIDReplace the placeholders. claim claims the name and asks the bot’s server to switch; switch retries that change. verify checks whether the handle is live. Read the actual returned status before retrying: a pending change may simply need time, while a manual response needs your action. See handle verification.
Doctor and CI: distinguish the server from the CLI release
The checked npm package is 0.1.0, even though the source repository describes later work. It does not include doctor, listing or support for BSBOT_TOKEN. The unknown-command captures below are real; they are not successful checkups or listing updates.
bsbot 0.1.0 ·
Local command; no account connection · Exit code 2
bsbot doctor --json{"error":{"code":"usage","message":"Unknown command \"doctor\". See bsbot --help."}}
bsbot 0.1.0 ·
Local command; no account connection · Exit code 2
bsbot listing get cli --json{"error":{"code":"usage","message":"Unknown command \"listing\". See bsbot --help."}}
Use the dashboard’s checkup for now. The API reference describes the authenticated doctor and listing endpoints and listing-only deploy tokens. For CI, follow that HTTP contract, store the secret in your CI secret store and restrict a deploy token to the intended bot. An HTTP example does not establish support for an unreleased bsbot listing set command. The CLI reference remains the place for command compatibility details.
Read-only AT Protocol work with goat
This session resolves the public DID of bsky.app. It does not log in or change the account. The returned DID document identifies the handle, public key and service endpoint at the capture time. Repository exports and migrations are separate commands with separate risks; consult the versioned goat source before using them.
goat goat version 0.2.9 ·
Read-only public AT Protocol data · Exit code 0
goat resolve did:plc:z72i7hdynmk6r22z27h6tvur{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1",
"https://w3id.org/security/suites/secp256k1-2019/v1"
],
"id": "did:plc:z72i7hdynmk6r22z27h6tvur",
"alsoKnownAs": [
"at://bsky.app"
],
"verificationMethod": [
{
"id": "did:plc:z72i7hdynmk6r22z27h6tvur#atproto",
"type": "Multikey",
"controller": "did:plc:z72i7hdynmk6r22z27h6tvur",
"publicKeyMultibase": "zQ3shQo6TF2moaqMTrUZEM1jeuYRQXeHEx4evX9751y2qPqRA"
}
],
"service": [
{
"id": "#atproto_pds",
"type": "AtprotoPersonalDataServer",
"serviceEndpoint": "https://puffball.us-east.host.bsky.network"
}
]
}
Posting and timelines with bsky
The captured help is from the downloaded mattn/bsky 0.0.82 release. It lists timeline, posting and account operations. We did not log in or run any of its write commands. Its upstream documentation is a capability source, not evidence that our session tested every command.
bsky bsky version 0.0.82 ·
Local command; no account connection · Exit code 0
bsky --helpNAME: bsky - bsky USAGE: bsky [global options] command [command options] VERSION: 0.0.82 DESCRIPTION: A cli application for bluesky COMMANDS: show-profile Show profile update-profile Update profile show-session Show session timeline, tl Show timeline stream Show timeline as stream thread Show thread post Post new text vote Vote the post votes Show votes of the post repost Repost the post reposts Show reposts of the post follow Follow the handle unfollow Unfollow the handle follows Show follows followers Show followers block Block the handle unblock Unblock the handle blocks Show blocks mute Mute the handle unmute Unmute the handle mutes Show muted users report Report the handle moderation-list Add the handle to a new moderation list lists Show lists list Show list items chat Direct messages delete Delete the note search Search Bluesky search-actors Search Actors login Login the social notification, notif Show notifications invite-codes Show invite codes list-app-passwords Show App-passwords add-app-password Add App-password revoke-app-password Revoke App-password mcp Start MCP server help, h Shows a list of commands or help for one command GLOBAL OPTIONS: -a value profile name -V verbose (default: false) --help, -h show help --version, -v print the version
Keep each credential within its purpose
bsbot stores its own token in ~/.config/bsbot/credentials.json, with user-only permissions; the default lifetime is 30 days. bsbot logout revokes that token. The dashboard can revoke CLI access too. Keep credentials out of logs and source control.
For clients that use a Bluesky password argument, create an app password instead of supplying the account password. goat documents storing its app password and tokens on disk; its logout removes that local authentication file. A posting client’s credentials can permit posts and other account changes, unlike a Bluesky.bot handle token. Review scopes, local storage and revocation before enabling unattended jobs.