bluesky_cli 0.6.11

A powerful CLI tool that allows Bluesky Social's APIs to be executed from the command line powered by Dart language.

A Powerful and Useful CLI Tool for Bluesky Social 🦋

• 1. Guide 🌎
  • 1.1. Getting Started ⚡
    • 1.1.1. Install
    • 1.1.2. Usage
    • 1.1.3. Queries and Procedures
    • 1.1.4. Records
    • 1.1.5. Authentication
      • 1.1.5.1. Global Options
      • 1.1.5.2. Auth Service vs. Service
      • 1.1.5.3. Public Endpoints
      • 1.1.5.4. Secure Password Entry
      • 1.1.5.5. Session Cache
      • 1.1.5.6. Environment Variables
  • 1.2. Tips 🏄
    • 1.2.1. Prettify JSON
    • 1.2.2. Show Status and Request
    • 1.2.3. Use Another Service

1. Guide 🌎

A powerful CLI tool that allows Bluesky Social's APIs to be executed from the command line powered by Dart language.

The commands are automatically generated from the official AT Protocol lexicons, so every command, argument name, and default value conforms to the official API definitions.

1.1. Getting Started ⚡

1.1.1. Install

dart pub global activate bluesky_cli

1.1.2. Usage

Commands are grouped by lexicon namespace. For example, the APIs under app.bsky.feed.* are available from the app-bsky-feed command.

A powerful and extensible CLI tool for interacting with Bluesky Social's APIs

Usage: bsky <command> [arguments]

Global options:
-h, --help                    Print this usage information.
    --identifier              Handle or email address for authentication.
    --password                Password on Bluesky for authentication.
    --password-stdin          Read the password for authentication from stdin.
    --service                 Name of the service to send the request to.
    --auth-service            Name of the service to authenticate against (createSession).
    --[no-]auth               Whether to authenticate when credentials are available.
                              (defaults to on)
    --[no-]session-cache      Whether to cache the session at ~/.config/bsky/session.json.
                              (defaults to on)
    --timeout                 Request timeout in seconds.
    --pretty                  Enable to output JSON in pretty format.
    --status                  Enable to output status code and reason phrase.
    --request                 Enable to output request method and URI.
    --verbose                 Enable verbose logging.
-v, --version                 Print the version of this CLI.

Available commands:
  app-bsky-actor                Provides commands for app.bsky.actor.*
  app-bsky-feed                 Provides commands for app.bsky.feed.*
  app-bsky-graph                Provides commands for app.bsky.graph.*
  app-bsky-notification         Provides commands for app.bsky.notification.*
  app-bsky-video                Provides commands for app.bsky.video.*
  cardyb                        Extracts a link preview from a URL.
  chat-bsky-actor               Provides commands for chat.bsky.actor.*
  chat-bsky-convo               Provides commands for chat.bsky.convo.*
  com-atproto-identity          Provides commands for com.atproto.identity.*
  com-atproto-repo              Provides commands for com.atproto.repo.*
  com-atproto-server            Provides commands for com.atproto.server.*
  com-atproto-sync              Provides commands for com.atproto.sync.*
  tools-ozone-moderation        Provides commands for tools.ozone.moderation.*
  ...

Run "bsky help <command>" for more information about a command.

1.1.3. Queries and Procedures

Each XRPC method is a subcommand named after the lexicon method in kebab-case, and its options match the lexicon parameters.

# app.bsky.actor.getProfile
bsky app-bsky-actor get-profile --actor shinyakato.dev

# app.bsky.feed.getTimeline (requires auth)
bsky app-bsky-feed get-timeline --limit 10

# com.atproto.repo.uploadBlob (binary input, requires auth)
bsky com-atproto-repo upload-blob --file ./avatar.png

1.1.4. Records

Record lexicons such as app.bsky.feed.post provide create, put, delete, get and list subcommands based on com.atproto.repo.*.

# Create a post.
bsky app-bsky-feed post create --text "Hello, Bluesky!" --createdAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)"

# Get a post record. --repo defaults to the authenticated user.
bsky app-bsky-feed post get --repo bsky.app --rkey 3l6oveex3ii2l

# List post records.
bsky app-bsky-feed post list --repo bsky.app --limit 10

# Delete a post record.
bsky app-bsky-feed post delete --rkey 3l6oveex3ii2l

JSON parameters like facets and embed accept raw JSON strings:

bsky app-bsky-feed post create \
  --text "check this out" \
  --createdAt "2024-01-01T00:00:00Z" \
  --embed '{"$type":"app.bsky.embed.external","external":{"uri":"https://atprotodart.com","title":"atproto.dart","description":"..."}}'

1.1.5. Authentication

The following methods are available to authenticate with Bluesky Social via this CLI tool.

1.1.5.1. Global Options

Authentication data can be specified for identifier and password in Global Options.

bsky app-bsky-feed get-timeline --identifier=shinyakato.dev --password=xxxxxxxxx

1.1.5.2. Auth Service vs. Service

Since v0.6.0 the endpoint that receives your raw credentials is separated from the endpoint that serves the request. --auth-service is the service createSession authenticates against (your own PDS, bsky.social by default), while --service is where the actual XRPC request is sent.

This separation exists so your handle and password are only ever sent to your own PDS — never to a third-party AppView or PDS you happen to query.

# Authenticate against your PDS, but read the timeline from the public AppView.
bsky app-bsky-feed get-timeline \
  --auth-service pds.example.com \
  --service public.api.bsky.app

When --auth-service is omitted it defaults to bsky.social, so existing invocations keep working unchanged.

1.1.5.3. Public Endpoints

Many app.bsky.* reads are available on the public AppView without a session. Pass --no-auth to send an unauthenticated request; no createSession call is made and no credentials are read, even if they are present in the environment.

bsky app-bsky-actor get-profile --actor bsky.app \
  --service public.api.bsky.app --no-auth

--auth is the default and can be given explicitly to force authentication.

1.1.5.4. Secure Password Entry

Passing --password on the command line leaves the secret in your shell history and process list. Use --password-stdin to read the password from stdin instead — piped from a secret manager, or typed interactively (terminal echo is disabled while it is read).

# From a secret manager (no password in argv or history).
some-secret-tool get bluesky-password | \
  bsky app-bsky-feed get-timeline --identifier shinyakato.dev --password-stdin

# Typed interactively (input is not echoed).
bsky app-bsky-feed get-timeline --identifier shinyakato.dev --password-stdin

1.1.5.5. Session Cache

By default the session returned by createSession is cached at ~/.config/bsky/session.json (created with 0600 permissions) and reused across invocations, refreshing when the access token expires. This avoids a fresh password login on every call, which would otherwise trip createSession rate limits.

Pass --no-session-cache to always create a fresh session and never write the cache file.

bsky app-bsky-feed get-timeline --no-session-cache

1.1.5.6. Environment Variables

By setting the authentication data in the environment variable, the specification of authentication data in Global Options can be omitted.

Environment Variable	Equivalent Option
BLUESKY_IDENTIFIER	identifier
BLUESKY_PASSWORD	password

Then you can call like:

bsky app-bsky-feed get-timeline

1.2. Tips 🏄

1.2.1. Prettify JSON

The JSON output from this CLI tool is unformatted, but you can use the following options to output JSON in a formatted state.

bsky app-bsky-feed get-timeline --pretty

1.2.2. Show Status and Request

The status code and request URI are not output by default, but can be output with the following options.

bsky app-bsky-feed get-timeline --status --request

1.2.3. Use Another Service

Requests are sent to bsky.social by default. Use --service to send them to another PDS or the public AppView.

bsky app-bsky-actor get-profile --actor bsky.app --service public.api.bsky.app