🐦 Perch

A beautiful terminal social client for Mastodon and Bluesky

Read, post, and engage across social networks — all from your terminal.

📖 Table of Contents

• ✨ Features
• 📸 Screenshots
• 🚀 Quick Start
• 🔐 Authentication
• 💻 Usage
• ⌨️ Keybindings
• 🎨 Themes
• ⚙️ Configuration
• 🏗️ Architecture
• 🔧 Building from Source
• 🤝 Contributing
• 📄 License

✨ Features

Feature Highlights

📸 Screenshots

Timeline View — Browse posts from all your networks

Compose Post — Write once, post everywhere

Accounts — Manage your connected accounts

Keyboard Shortcuts — Vim-style navigation

Theme Picker — 15 beautiful themes

About — Version info and links

🚀 Quick Start

Installation

macOS

# Homebrew (recommended - fast, pre-built binary)
brew install ricardodantas/tap/perch

Linux

# Homebrew (recommended)
brew install ricardodantas/tap/perch

# Or via Cargo
cargo install perch

Windows

# Via Cargo (requires Rust toolchain)
cargo install perch

Or download perch-*-x86_64-pc-windows-msvc.zip from GitHub Releases.

From Source

git clone https://github.com/ricardodantas/perch
cd perch
cargo install --path .

First Run

1. Add a Mastodon account:

perch auth mastodon mastodon.social

2. Or add a Bluesky account:

perch auth bluesky

3. Launch the TUI:

perch

🔐 Authentication

Mastodon (OAuth)

perch auth mastodon <instance>

This will:

1. Register Perch with your Mastodon instance
2. Open your browser for authorization
3. Ask you to paste the authorization code
4. Store credentials securely in your system keyring

Examples:

perch auth mastodon mastodon.social
perch auth mastodon fosstodon.org
perch auth mastodon hachyderm.io

Bluesky (App Password)

perch auth bluesky

You'll need an App Password from Bluesky settings.

Note: App passwords are more secure than your main password — they can be revoked individually and don't have full account access.

💻 Usage

TUI Mode

perch

Launch the beautiful terminal interface with three-panel layout:

• Left panel: Accounts and filters
• Center panel: Timeline/feed
• Right panel: Post details and media

CLI Commands

Posting

# Post to all configured networks
perch post "Hello world!"

# Post to specific networks
perch post "Hello Fediverse!" --to mastodon
perch post "Hello everyone!" --to mastodon,bluesky

# Post with content warning
perch post "Spoiler content" --cw "Movie spoilers"

# Post with media
perch post "Check this out!" --media ~/photo.jpg

Scheduled Posts

# Schedule a post for later
perch post "Good morning!" --schedule "in 2h"
perch post "Happy Friday!" --schedule "YYYY-MM-DD HH:MM" --to mastodon,bluesky

# List pending scheduled posts
perch schedule list

# Cancel a scheduled post
perch schedule cancel abc123

# Process due scheduled posts (one-time)
perch schedule run

# Run scheduler daemon (continuous)
perch schedule daemon
perch schedule daemon --interval 30  # Check every 30 seconds

Schedule time formats:

• Relative: "in 5m", "in 2h", "in 1d", "in 30 minutes"
• Time today: "15:00", "3pm" (schedules for tomorrow if past)
• Date+time: "YYYY-MM-DD HH:MM", "YYYY-MM-DDTHH:MM"

TUI Scheduling: In the compose dialog (n), press Tab to switch to the schedule input field. Type your schedule time and it validates in real-time. Press Tab or Enter to confirm, F4 to clear.

Timeline

# View home timeline (all networks)
perch timeline

# View specific network
perch timeline mastodon
perch timeline bluesky

# Limit posts
perch timeline --limit 50

Account Management

# List all accounts
perch accounts

# Remove an account
perch accounts remove <account-id>

⌨️ Keybindings

Global

Navigation

Timeline View

Compose

🎨 Themes

Perch includes 15 beautiful themes based on popular terminal and editor color schemes.

Press t in the TUI to cycle through themes.

Available Themes

⚙️ Configuration

Perch uses TOML for configuration. The config file is located at:

~/.config/perch/config.toml

Full Configuration Example

# ─────────────────────────────────────────────────────────────
# Display Settings
# ─────────────────────────────────────────────────────────────

# Theme (dracula, nord, catppuccin-mocha, etc.)
theme = "dracula"

# Enable vim-like keybindings
vim_mode = true

# Show media previews (when supported)
show_media = true

# ─────────────────────────────────────────────────────────────
# Timeline Settings
# ─────────────────────────────────────────────────────────────

# Default timeline view
default_timeline = "home"

# Number of posts to fetch
post_limit = 50

# Auto-refresh interval in seconds (0 = manual only)
refresh_interval_secs = 0

# ─────────────────────────────────────────────────────────────
# Posting Settings
# ─────────────────────────────────────────────────────────────

# Default visibility for posts
# Options: public, unlisted, private, direct
default_visibility = "public"

# Default networks to post to (when using CLI without --to)
default_networks = ["mastodon", "bluesky"]

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User                                │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│     perch (TUI)         │     │     perch (CLI)         │
│  • Browse timelines     │     │  • perch post           │
│  • Compose posts        │     │  • perch timeline       │
│  • Like & boost         │     │  • perch accounts       │
│  • Switch themes        │     │  • Scriptable commands  │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Core Library                           │
│  • api/mastodon.rs  — Mastodon OAuth + API                  │
│  • api/bluesky.rs   — AT Protocol integration               │
│  • auth/            — System keyring storage                │
│  • db.rs            — SQLite cache & drafts                 │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│   🐘 Mastodon API       │     │   🦋 Bluesky API        │
│   (Any instance)        │     │   (bsky.social)         │
└─────────────────────────┘     └─────────────────────────┘

Project Structure

perch/
├── src/
│   ├── api/              # Network API clients
│   │   ├── mod.rs        # Unified SocialApi trait
│   │   ├── mastodon.rs   # Mastodon OAuth + REST
│   │   └── bluesky.rs    # AT Protocol client
│   ├── app/              # TUI application
│   │   ├── mod.rs
│   │   ├── state.rs      # Application state
│   │   ├── events.rs     # Key event handling
│   │   └── ui.rs         # UI rendering
│   ├── auth/             # Credential storage
│   │   └── mod.rs        # System keyring
│   ├── models/           # Data models
│   │   ├── mod.rs
│   │   ├── account.rs
│   │   ├── network.rs
│   │   └── post.rs
│   ├── config.rs         # Configuration loading
│   ├── db.rs             # SQLite database
│   ├── theme.rs          # Color themes
│   ├── lib.rs            # Library root
│   └── main.rs           # Entry point
├── Cargo.toml
└── LICENSE

🔧 Building from Source

Requirements

• Rust 1.85+
• Linux, macOS, or Windows

Build

# Clone the repository
git clone https://github.com/ricardodantas/perch
cd perch

# Build release binary
cargo build --release

# The binary will be at:
# target/release/perch

# Or install directly
cargo install --path .

Development

# Run in development
cargo run

# Run tests
cargo test

# Run linter
cargo clippy

# Format code
cargo fmt

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cargo test
5. Run clippy: cargo clippy
6. Format: cargo fmt
7. Commit: git commit -m "Add amazing feature"
8. Push: git push origin feature/amazing-feature
9. Open a Pull Request

📄 License

This project is licensed under the GPL-3.0-or-later license — see the LICENSE file for details.

_{Built with 🦀 Rust and ❤️ by Ricardo Dantas}