bluesky_cli

AT Protocol and Bluesky Social Things for Dart/Flutter

---

---

• 1. About atproto.dart 💪
• 2. Package Ecosystem 📦
  • 2.1. Core Libraries
  • 2.2. Client Libraries
  • 2.3. Utilities & Tools
  • 2.4. CLI Tool
  • 2.5. GitHub Actions Workflow
• 3. Quick Start Guide 🚀
  • 3.1. Building a Bluesky Social App
  • 3.2. Building AT Protocol Services
• 4. Project Development Setup 🛠️
  • 4.1. Prerequisites
  • 4.2. Quick Setup
  • 4.3. Development Commands
  • 4.4. Troubleshooting
  • 4.5. Contributing
• 5. Who is using atproto.dart? 👀
• 6. Support

Welcome to atproto.dart 🦋

The comprehensive Dart/Flutter SDK for the AT Protocol ecosystem - empowering developers to build the next generation of decentralized social applications with Bluesky and beyond.

1. About atproto.dart 💪

The AT Protocol represents a paradigm shift toward decentralized social networking, and Bluesky is leading this transformation. As the ecosystem grows rapidly with millions of users and thousands of developers building innovative applications, the need for robust, well-designed development tools has never been greater.

atproto.dart is the most comprehensive and battle-tested SDK for AT Protocol development in Dart and Flutter. Whether you're building mobile apps, web applications, bots, or backend services, our SDK provides everything you need to integrate with the AT Protocol ecosystem efficiently and reliably.

Why Choose atproto.dart?

For Mobile & Web Developers:

• Build cross-platform social apps with Flutter using production-ready AT Protocol integration
• Access the complete Bluesky API including posts, feeds, profiles, messaging, and moderation
• Leverage built-in OAuth DPoP authentication for secure user sessions

For Backend & Bot Developers:

• Create powerful automation tools and bots with comprehensive API coverage
• Process real-time data streams using our optimized Firehose implementation
• Build custom AT Protocol services and bridges to other platforms
• Access Ozone moderation tools for administrative operations

For AT Protocol Enthusiasts:

• Work with all core AT Protocol primitives: DIDs, NSIDs, AT URIs, Lexicons, and XRPC
• Contribute to the growing ecosystem of decentralized social applications
• Access cutting-edge features as the protocol evolves

Proven in Production: Used by popular applications like SkyFeed, deck.blue, SkyThrow, and many others serving thousands of users daily. Our SDK is actively maintained, thoroughly tested, and designed for the demands of production applications.

2. Package Ecosystem 📦

The atproto.dart ecosystem is organized into focused packages that work together seamlessly. Choose the packages that match your project's needs, from low-level AT Protocol primitives to high-level client libraries.

2.1. Core Libraries

Foundation packages for AT Protocol primitives and data structures

Package	Description	pub.dev	Docs
at_primitives	AT Protocol primitive types (identifiers, URIs, NSIDs) - unified package		README
xrpc	XRPC HTTP client with built-in retry and error handling		README
multiformats	IPFS multiformats support for content addressing (CIDs, multihash, etc.)		README
lexicon	Lexicon schema parsing and validation		README
atproto_core	Shared utilities and base functionality for AT Protocol clients		README

2.2. Client Libraries

High-level API clients for AT Protocol services

Package	Description	pub.dev	Docs
atproto	Complete AT Protocol client (com.atproto.* endpoints) with Firehose support		README / GUIDE
bluesky	Full-featured Bluesky client (app.bsky.*, chat.bsky.* + AT Protocol)		README / GUIDE
atproto_oauth	OAuth DPoP authentication client for secure user sessions		README
did_plc	PLC Directory client for DID resolution and management		README
atproto_identity	Identity resolution (handle/DID → PDS + signing key) and service-auth JWT verification		README

2.3. Utilities & Tools

Specialized packages for text processing

Package	Description	pub.dev	Docs
bluesky_text	Rich text parsing for mentions, links, hashtags, and formatting		README / GUIDE
bluesky_text_flutter	Flutter widgets for bluesky_text: a rich-text editing controller and a post viewer		README

2.4. CLI Tool

Tool	Install	Docs
bluesky_cli: command line tool for app.bsky.* endpoints	dart pub global activate bluesky_cli	README

2.5. GitHub Actions Workflow

Workflow	Marketplace	Docs
bluesky-post: workflow for scheduled post to Bluesky from GitHub Actions		README

3. Quick Start Guide 🚀

Get up and running with AT Protocol and Bluesky in minutes. Choose your use case below:

3.1. Building a Bluesky Social App

Perfect for creating mobile apps, web clients, or social features.

dart pub add bluesky

import 'package:bluesky/atproto.dart';
import 'package:bluesky/bluesky.dart';

void main() async {
  // Create authenticated session
  final session = await createSession(
    identifier: 'your-handle.bsky.social',
    password: 'your-password',
  );

  final bsky = Bluesky.fromSession(session.data);

  // Post to Bluesky
  await bsky.feed.post.create(text: 'Hello from atproto.dart!');

  // Get your timeline
  final timeline = await bsky.feed.getTimeline();
  for (final post in timeline.data.feed) {
    print('${post.post.author.displayName}: ${post.post.record}');
  }
}

Next Steps:

• Complete Bluesky Guide - Authentication, posting, feeds, profiles
• Supported Bluesky APIs - All available endpoints

3.2. Building AT Protocol Services

Ideal for bots, backend services, or custom AT Protocol implementations.

dart pub add atproto

import 'package:atproto/atproto.dart';
import 'package:atproto/firehose.dart';
import 'package:atproto/com_atproto_sync_subscriberepos.dart';

void main() async {
  final session = await createSession(
    service: 'https://bsky.social',
    identifier: 'your-handle.bsky.social',
    password: 'your-password',
  );

  // Connect to any AT Protocol service
  final atproto = ATProto.fromSession(session.data);

  // Create a record
  await atproto.repo.createRecord(
    repo: session.data.did,
    collection: 'app.bsky.feed.post',
    record: {
      'text': 'Hello AT Protocol!',
      'createdAt': DateTime.now().toUtc().toIso8601String(),
    },
  );

  final subscription = await atproto.sync.subscribeRepos();

  // Listen to the Firehose for real-time updates
  await for (final event in subscription.data.stream) {
    final repos = const SyncSubscribeReposAdaptor().execute(event);

    repos.whenOrNull(
      commit: (data) {
        print('New commit: ${data.repo}');
      },
    );
  }
}

Next Steps:

• AT Protocol Guide - Repository operations, Firehose, authentication
• Firehose Processing - Real-time data stream handling

3.3. Building a Custom Feed Generator

Want to publish your own algorithmic feed to Bluesky? A custom feed generator is a small HTTP service the AppView calls to get an ordered list of post URIs.

The templates/feed_generator template is a complete, runnable starting point — clone the directory, edit the algorithm, and deploy:

• bin/server.dart serves the three endpoints the AppView needs (/.well-known/did.json, app.bsky.feed.describeFeedGenerator, app.bsky.feed.getFeedSkeleton) and verifies each inbound service-auth JWT with atproto_identity.
• bin/publish_feed.dart registers the feed on the network (app.bsky.feed.generator record).
• A Firehose indexer, a FeedAlgorithm interface with a reverse-chronological sample, and a swappable FeedStore are included — replace the algorithm and store with your own.

# From a clone of this repository:
cd templates/feed_generator

export FEEDGEN_HOSTNAME=feed.example.com
export FEEDGEN_PUBLISHER_HANDLE=you.bsky.social
export FEEDGEN_PUBLISHER_PASSWORD=xxxx-xxxx-xxxx-xxxx

dart run bin/server.dart        # index the firehose and serve the feed
dart run bin/publish_feed.dart  # register the feed on the network

Next Steps:

• Feed Generator template README - Configuration, deployment, and customization
• Bluesky custom feeds overview - How feed generators fit into the network

4. Project Development Setup 🛠️

Contributing to atproto.dart or setting up the development environment? This project uses Melos for efficient monorepo management across all packages.

4.1. Prerequisites

• Dart SDK: Version 3.8.0 or higher (Install Dart)
• Git: For cloning and version control
• IDE: VS Code, IntelliJ, or any Dart-compatible editor

4.2. Quick Setup

# Clone the repository
git clone https://github.com/myConsciousness/atproto.dart.git
cd atproto.dart

# Install Melos globally
dart pub global activate melos

# Set up all packages (dependencies, code generation, etc.)
melos setup

The melos setup command handles everything: installing dependencies, running code generation, and preparing the development environment across all packages.

4.3. Development Commands

Command	Description
melos setup	Complete project setup - run this first!
melos get	Install dependencies for all packages
melos analyze	Run static analysis across all packages
melos test	Execute all tests in the project
melos fmt	Format code and organize imports
melos build	Run code generation for all packages
melos gen	Generate API clients from Lexicon schemas

Release commands (maintainers):

Command	Description
melos publish_dry	Dry-run publish for all Dart workspace packages (validate only) - run this first
melos publish_live	Publish all Dart packages to pub.dev and create git version tags
melos publish_tags	Push the git version tags created by melos publish_live to origin
melos flutter_publish_dry	Dry-run publish for the Flutter package (bluesky_text_flutter)
melos flutter_publish_live	Publish the Flutter package (bluesky_text_flutter) to pub.dev
melos flutter_publish_tags	Tag and push the Flutter package release

4.4. Troubleshooting

Setup Issues:

• "melos command not found": Ensure ~/.pub-cache/bin is in your PATH, or run dart pub global activate melos
• Build failures: Try melos clean followed by melos setup to reset the environment
• Version conflicts: Ensure you're using Dart 3.8.0+ with dart --version

Development Issues:

• Import errors: Run melos build to regenerate code
• Test failures: Check if you need to run melos gen to update generated API clients
• Dependency issues: Use melos get to refresh all package dependencies

Need Help?

• 📖 Contribution Guidelines - Detailed development workflow
• 🐛 Issue Tracker - Report bugs or request features
• 💬 Discussions - Ask questions and share ideas
• 🌐 Documentation - Complete guides and API references

4.5. Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation:

1. Fork the repository and create a feature branch
2. Make your changes following our coding standards (melos fmt helps!)
3. Add tests for new functionality (melos test to verify)
4. Update documentation if needed
5. Submit a pull request with a clear description

See our Contribution Guidelines for detailed information about the development process, coding standards, and how to submit changes.

5. Who is using atproto.dart? 👀

The following projects/services are using atproto.dart packages:

• APOD BOT (bot) maintained by @shinyakato.dev
• SkyFeed (web) maintained by @redsolver.dev
• SkyBridge (proxy) maintained by @videah.net
• SkyClad (mobile) maintained by @igz0.bsky.social
• deck.blue (web) maintained by @deck.blue
• SkyThrow (mobile) maintained by @rukari.bsky.social, @hidea.bsky.social

You can see more at showcase, special thanks!

6. Support