Raibid Labs Documentation

README

5 min read

raibid-cli

License Rust

Meta-management CLI for the raibid-labs GitHub organization

A terminal-based meta-management tool that provides organization-wide repository operations with an interactive TUI interface. Built with Rust, ratatui, and modern async patterns.

Overview

raibid-cli is designed to streamline the management of all repositories within the raibid-labs GitHub organization. It combines powerful command-line operations with an intuitive terminal user interface, enabling developers to efficiently clone, synchronize, and manage dozens of repositories simultaneously.

Key Features

  • Organization-Wide View: See all raibid-labs repositories at a glance
  • Batch Operations: Clone or sync multiple repositories concurrently
  • Interactive TUI: Navigate and manage repos with a keyboard-driven interface
  • Smart Filtering: Filter repositories by name, language, activity, and more
  • Safe by Default: Detects uncommitted changes and prevents destructive operations
  • Configuration-Driven: Customize behavior via TOML configuration files
  • Fast & Efficient: Built with Rust for maximum performance

Quick Start

Prerequisites

  • Rust 1.70 or later
  • GitHub CLI (gh) installed and authenticated
  • Just (for build automation) - cargo install just
  • Nushell (for automation scripts) - optional but recommended

Installation

# Clone the repository
git clone https://github.com/raibid-labs/raibid-cli.git
cd raibid-cli
 
# Build the project
just build
 
# Or build release version
just build-release
 
# Install globally
just install-cli

Basic Usage

# List all repositories
raibid list
 
# List with filtering
raibid list --filter "hack-*"
 
# Clone all repositories
raibid clone --all
 
# Sync all repositories
raibid sync --all
 
# Dry run to see what would happen
raibid sync --all --dry-run
 
# Launch interactive TUI
raibid tui
 
# Show help
raibid --help

Architecture

raibid-cli follows a modular architecture with three main components:

  1. Core Library (raibid-core) - Reusable functionality for GitHub API, Git operations, and synchronization
  2. CLI Interface - Command-line interface using clap for scripting and automation
  3. TUI Interface - Interactive terminal UI using ratatui for visual management

See architecture.md for detailed architecture documentation.

Project Structure

raibid-cli/
├── src/                    # CLI application source
│   └── main.rs            # Main entry point
├── crates/
│   └── raibid-core/       # Core library
│       └── src/
│           ├── config.rs  # Configuration management
│           ├── error.rs   # Error types
│           ├── filter.rs  # Repository filtering
│           ├── git.rs     # Git operations
│           ├── github.rs  # GitHub API integration
│           ├── sync.rs    # Synchronization engine
│           └── types.rs   # Shared data types
├── docs/                  # Documentation
│   ├── architecture.md    # Architecture overview
│   ├── roadmap.md        # Development roadmap
│   ├── research-git-sync.md
│   └── research-raibid-labs-org.md
├── scripts/               # Nushell automation scripts
│   ├── discover-repos.nu  # Repository discovery
│   ├── validate.nu        # Project validation
│   └── sync-repos.nu      # Repository synchronization
├── justfile               # Build automation recipes
├── Cargo.toml            # Workspace manifest
└── README.md             # This file

Development

Building

# Development build
just build
 
# Release build
just build-release
 
# Clean build artifacts
just clean

Testing

# Run all tests
just test
 
# Run tests with output
just test-verbose
 
# Run specific test
just test-name <test_name>
 
# Generate coverage report
just test-coverage

Code Quality

# Check code
just check
 
# Run linter
just lint
 
# Auto-fix lint issues
just lint-fix
 
# Format code
just fmt
 
# Run all CI checks
just ci

Development Workflow

# Watch and rebuild on changes
just watch
 
# Watch and rerun tests
just watch-test
 
# Setup dev environment
just setup-dev
 
# Quick start demo
just quick-start

Configuration

raibid-cli uses a TOML configuration file located at ~/.config/raibid-cli/config.toml.

Example configuration:

[general]
org = "raibid-labs"
workspace_root = "~/raibid-labs"
 
[sync]
concurrency = 5
auto_pull = true
check_uncommitted = true
 
[filter]
include = ["*"]
exclude = ["*.archive"]
exclude_archived = true
exclude_forks = false
 
[git]
ssh_auth = true
depth = 0  # 0 = full clone
 
[tui]
show_descriptions = true
compact_mode = false

See architecture.md#configuration for full configuration options.

Roadmap

raibid-cli is under active development. See roadmap.md for the complete development roadmap.

Current Phase: Foundation (Phase 1)

  • Project infrastructure
  • Core library structure
  • Basic CLI commands
  • GitHub API integration
  • Git operations
  • Configuration system

Upcoming Phases

  • Phase 2: Synchronization Engine - Robust repository sync with concurrency
  • Phase 3: TUI Implementation - Interactive terminal user interface
  • Phase 4: Advanced Features - Filtering, caching, statistics
  • Phase 5: Integration - raibid-labs ecosystem integration
  • Phase 6: Release - Production-ready v1.0.0

Documentation

User Documentation

Research Documentation

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

  1. Fork and clone the repository
  2. Install prerequisites (Rust, gh CLI, just)
  3. Run just setup-dev to install development tools
  4. Make your changes
  5. Run just ci to ensure quality checks pass
  6. Submit a pull request

License

Licensed under either of:

at your option.

Acknowledgments

raibid-cli is inspired by:

  • kubernetes/git-sync - Repository synchronization patterns
  • raibid-ci - TUI design and architecture patterns
  • The Rust ecosystem - Amazing libraries that make this possible

Contact

Made with ❤️ by the raibid-labs team

Graph View