Skip to Content
bsky-cli

⚑ Usage

Every bsky subcommand, its arguments and options, and what it prints.

Run bsky <command> for a one-shot action. Run bsky on its own to open the πŸ–₯️ interactive mode instead. bsky <command> --help lists a command's arguments.

Cheat sheet

TaskCommand
Postbsky post "Hello"
Post with an imagebsky post "Sunset" --image sunset.jpg --alt "Orange sky"
Self-threadbsky thread "First" "Second" "Third"
Replybsky reply <post-url> "Agreed"
Quotebsky quote <post-url> "Worth a read"
Delete your postbsky delete <post-url or rkey>
Your recent postsbsky list --limit 10
Home timelinebsky timeline
Notificationsbsky notifications
A profilebsky profile alice.example.com
A post and its repliesbsky view <post-url>
Search postsbsky search "atproto" --limit 50
Like / unlikebsky like <post-url>, bsky unlike <post-url>
Repost / undobsky repost <post-url>, bsky unrepost <post-url>
Follow / unfollowbsky follow <handle>, bsky unfollow <handle>

Posts and handles

Wherever a command asks for a post, it takes either a bsky.app web URL, such as https://bsky.app/profile/alice.example.com/post/3kxyz…, or an at:// URI. delete also takes the bare record key (the last segment of the URL).

Handles may be written with or without a leading @, and a did: identifier works too.

Writing

post

bsky post "<text>" [--image <path>] [--alt <text>] [--reply-to <url>] [--quote <url>] [--lang <code>]
OptionEffect
--imageAttach one image: .png, .jpg, .jpeg, .gif or .webp
--altAlt text for that image
--reply-toPost as a reply to this post, inside its thread
--quoteEmbed this post as a quote
--langTag the post with a language code, such as en or fr
--yesAccepted and ignored, for compatibility with older scripts

--image and --quote cannot be combined: when both are given, the image is attached and the quote is dropped.

Links, #hashtags and @handle.example.com mentions in the text are turned into rich text automatically, so they are clickable on Bluesky. A domain such as kud.io becomes a link without needing https://.

thread

bsky thread "First post" "Second post" "Third post"

Each argument becomes one post, and each post replies to the one before it. At least two are required. Every post is length-checked before anything is sent, so one over-long post stops the whole thread rather than leaving half of it published.

reply and quote

bsky reply <post-url> "Your reply"
bsky quote <post-url> "Your comment"

Shortcuts for post --reply-to and post --quote.

delete

bsky delete <post-url or rkey>

Deletes one of your own posts and prints βœ“ Deleted.

Length and output

Bluesky allows 300 characters per post. Anything longer fails with Post is <n> chars β€” Bluesky limit is 300.

On success, post, reply and quote print the web URL of the new post:

βœ“ https://bsky.app/profile/alice.example.com/post/3kxyz…

thread prints βœ“ Posted a <n>-post thread followed by the URL of its first post.

Reading

CommandShowsOptions
bsky listYour own recent posts, each with its age and web URL--limit (default 25)
bsky timelineYour home timeline--limit (default 25)
bsky notificationsWho did what (the reason, such as like, repost or follow), with a snippet of text; unread ones marked ●--limit (default 25)
bsky profile [handle]Name, bio, followers, following and post count; yourself when no handle is givennone
bsky view <post-url>A post followed by its direct replies (up to 25)none
bsky search "<query>"Posts matching the query--limit (default 25)

Feed output gives each post its author, age (5m, 3h, 2d), text, and like, repost and reply counts.

Engaging

bsky like <post-url>
bsky unlike <post-url>
bsky repost <post-url>
bsky unrepost <post-url>
bsky follow <handle>
bsky unfollow <handle>

Each prints βœ“ <command> when it succeeds, for example βœ“ like.

Scripting

  • Every failure prints its message to stderr and exits with status 1, so set -e and && chains behave.
  • Colour is only used when stdout is a terminal; piped output is plain text.
  • Credentials come from the environment (see πŸ” Authentication), so nothing prompts.
bsky post "New release is out: kud.io" && echo "announced"