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.

Versions and sources checked on 16 November 2026. Help and public-read captures do not test authenticated changes.
Tool and versionBest fitAuthentication and writesInstall and licenceSource 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

bash
npm install --global @blueskydotbot/[email protected]
bsbot --version
bsbot --help

The 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

bash
bsbot --help
bsbot 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

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

bash
bsbot login
bsbot whoami
bsbot bots

After choosing your own bot DID and a free name, the published syntax is:

bash
bsbot claim BOT_DID chosen-name
bsbot switch BOT_DID
bsbot verify BOT_DID

Replace 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

bash
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

bash
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

bash
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

bash
bsky --help
NAME:
   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.

Questions about Bluesky CLIs

Can bsbot post to Bluesky?
No. The checked npm version manages Bluesky.bot handles and browses its directory. Use a posting client or the AT Protocol SDK for posts.
Why does bsbot doctor say unknown command?
The recorded npm 0.1.0 package has no doctor or listing command. A server endpoint alone does not add a command to an installed CLI. Check the release notes before relying on a newer capability.
Can I use the published bsbot in CI with BSBOT_TOKEN?
The checked 0.1.0 package does not read that environment variable. The server provides listing-only deploy tokens for direct HTTP requests; use its API reference and keep secrets in your CI secret store.

Sources