BlueCLIent - Bluesky TUI

A comprehensive Bluesky client with a modern TUI (Terminal User Interface) built using Textual framework. Features post scheduling, feed management, and real-time firehose access.

BlueCLIent Interface

Project Overview

BlueCLIent provides a powerful terminal-based interface for interacting with the Bluesky social media platform, combining the efficiency of command-line tools with a modern, intuitive UI.

Key Features

Users

Multi-Account Support

Manage multiple Bluesky accounts simultaneously

Clock

Post Scheduling

Queue posts for future publication with retry logic

Rss

Feed Management

Browse, filter, and search Bluesky feeds

Image

Media Handling

Upload and manage images and media content

Zap

Real-time Firehose

Live streaming of Bluesky network activity

Terminal

Modern TUI

Keyboard shortcuts and responsive design

Architecture Overview

Core Components

1. Main Application (shell.py)

The primary TUI application using Textual framework:

Tabbed interface layout
Application state management
Component integration

Main Interface

2. Bluesky Client (bsky/client.py)

Handles all Bluesky API interactions:

Multi-account support
Authentication and session management
Post creation and feed operations

3. Task Scheduler (scheduler/)

Post scheduling and task management system:

executor.py - Task execution with retry logic
storage.py - JSON-based task persistence
models.py - Task data structures

Task Scheduler

4. UI Widgets (widgets/)

Reusable TUI components:

collection_browser.py - Navigation and collection management
post_details_area.py - Post content display
feed_filter.py - Feed filtering and search
method_selector.py - API-style interface

Development Commands

Running the Application

# Main application
python shell.py

# Run tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_replies.py

Testing Components

# Test the scheduler
python test_scheduler_basic.py
python test_task_executor.py

# Test firehose functionality
python test_firehose.py

# Run profiling
python run_profiler.py

Installation

Dependencies

# Install dependencies
pip install -r requirements.txt

Core Dependencies

textual>=0.60.0 - TUI framework
rich>=13.0.0 - Rich text formatting
atproto - Bluesky AT Protocol client
python-dotenv - Environment variable management
pyyaml - YAML configuration handling

Feed View

Configuration

Environment Variables

Create a .env file with your Bluesky credentials:

# Primary account
BLUESKY_HANDLE=your.handle
BLUESKY_PASSWORD=your-password

# Additional accounts (numbered suffixes)
BLUESKY_HANDLE_2=second.handle
BLUESKY_PASSWORD_2=second-password

Multi-Account Setup

Multiple Accounts

Configure multiple Bluesky accounts using numbered environment variables. The application will automatically detect and load all configured accounts.

Features in Detail

Post Scheduling

Queue posts for future publication with advanced features:

Post Scheduling

Retry logic - Automatic retry on failure
Task persistence - Saved to scheduled_tasks.json
Status tracking - Monitor task execution
Queue management - View and manage scheduled posts

Feed Management

Browse and interact with Bluesky feeds:

Feed Management

Feed browsing - Navigate through posts
Filtering - Search and filter content
Real-time updates - Live feed refresh
Post interactions - Like, repost, reply

Media Handling

Preview support - Media preview in terminal

Firehose Access

Real-time Bluesky network streaming:

Firehose

The application includes real-time firehose access for live data streaming:

Real-time subscription - Uses atproto.FirehoseSubscribeReposClient
Message parsing - Process firehose data with parse_subscribe_repos_message
Live streaming - Receive commits, posts, and repository updates
Network monitoring - Track Bluesky network activity

Firehose Capabilities:

Real-time post discovery and monitoring
Live feed updates without polling
Network activity monitoring
Content filtering and analysis

Data Storage

File Structure

blueclient/
├── scheduled_tasks.json      # Persistent task storage
├── test_executor.log         # Execution logs
├── bluesky_tui.log          # Debug and operation logs
├── shell.py                  # Main application
├── bsky/                     # Bluesky client
│   └── client.py
├── scheduler/                # Task scheduler
│   ├── executor.py
│   ├── storage.py
│   └── models.py
├── widgets/                  # UI components
│   ├── collection_browser.py
│   ├── post_details_area.py
│   ├── feed_filter.py
│   └── themes.py
└── tests/                    # Test suite

Application Structure

UI Styling

Themes and Customization

Primary styling - shell.scss for main application theme
Built-in themes - Available in widgets/themes.py
Responsive design - Tabbed layout inspired by API clients
Keyboard shortcuts - Efficient navigation

Theme Customization

Testing

Test Suite

Test files in tests/ directory:

# Reply handling
python -m pytest tests/test_replies.py

# Media embed handling
python -m pytest tests/test_embeds.py

# Task queue UI
python -m pytest tests/test_task_queue_tab.py

# Media detection
python -m pytest tests/test_media_detection.py