Corral

corralctl

Automatically clone and organise repositories from GitHub, GitLab, Gitea, Forgejo, Codeberg and Bitbucket using Finder-friendly collections, ecosystems, and metadata.

---

Contents

Getting started

• Install — mise, Homebrew, Arch, Nix, Go, or from source
• Quick Start — clone and organise in one command

Features & Capabilities

• Features — structured layout, concurrency, and security
• Architecture — end-to-end flow from API fetch to per-repo dispatch
• Interactive TUI Mode — keybindings, commands, and autocomplete
• Layout Customization — Apple-style collections, ecosystems, and custom templates
• Smart Syncing — network-optimised incremental updates
• Exec Mode — concurrent batch execution of Git commands
• Mirror to other forges — corralctl sync pushes the tree to GitLab, Gitea, Forgejo, Codeberg, Bitbucket or GitHub
• MCP Server — expose your local workspace to AI coding agents
• Cross-repository symbol lookup — find where anything is defined, across every clone

Reference & Operational

• Usage & Flags — complete CLI parameter reference
• Examples — index of runnable programmatic examples
• Troubleshooting — quick solutions to common errors
• Frequently Asked Questions — design decisions and Windows/WSL support

Project

• Documentation — manual, API reference, developer docs
• When not to use corralctl — honest limits
• Requirements & toolchain policy — the Go floor and when it moves
• Stability guarantees — what a breaking change means here
• Security & hardening — reporting, posture, fuzzing
• License

---

Install

mise (macOS / Linux)

mise use -g github:sebastienrousseau/corralctl

This installs the latest released corralctl binary and keeps it managed with the rest of your mise tools.

Homebrew (macOS)

brew install sebastienrousseau/tap/corralctl

Homebrew here is a cask, which is a macOS-only mechanism — brew install on Linux will refuse it. On Linux use the .deb/.rpm packages or the tarballs attached to each release, or install with mise or the Go toolchain.

Arch Linux (AUR)

yay -S corralctl-bin    # or: paru -S corralctl-bin

Nix (any platform)

nix run github:sebastienrousseau/corralctl -- --help   # run without installing

nix profile install github:sebastienrousseau/corralctl # install

The flake ships the binary with its manpages and shell completions, and nix develop gives a shell with every tool the project's CI gates need, pinned by flake.lock.

Go toolchain

go install github.com/sebastienrousseau/corralctl/cmd/corralctl@latest

Installs into $(go env GOPATH)/bin (or $GOBIN when set). Note that a binary built this way reports corralctl version dev: the real version is stamped by the release pipeline through -ldflags, which go install does not apply. Use a release artefact if you need --version to be meaningful.

Build from source

Requires Git and Go at or above the go directive in go.mod, but not Go 1.27.0 to 1.27.2, which carry a reachable crypto/x509 advisory (see the minimum toolchain policy):

git clone https://github.com/sebastienrousseau/corralctl.git

cd corral make install # installs ~/.local/bin/corralctl

Platform Prerequisites

macOS

brew install go git gh

Ubuntu / Debian / WSL2

sudo apt install golang git

Install gh separately following the GitHub CLI installation guide.

Fedora / RHEL

sudo dnf install golang git gh

---

Quick Start

Run corralctl clone with an owner name (GitHub username or organization) to clone and automatically sort all repositories into a clean local directory hierarchy:

# Log in to GitHub CLI first (or set GITHUB_TOKEN)

gh auth login

Clone and organise every repository for your profile

corralctl clone my-username

The bare form, corralctl my-username, does the same thing. One binary, one base command, and every operation is a subcommand of it:

This converges your local directory structure into a structured mirror:

~/Code/

├── Public/ │ ├── Go/ │ │ └── corral/ │ ├── Rust/ │ │ └── my-crate/ │ └── Web/ │ └── project.github.io/ ├── Private/ │ └── Python/ │ └── internal-tool/ ├── Forks/ │ └── Rust/ │ └── upstream-project/ └── Work/

On macOS, corralctl also writes native Finder Tags to repository folders while preserving tags you added yourself. This keeps the physical hierarchy shallow and makes Finder searches and Smart Folders useful across ecosystems.

---

Features

---

Architecture

A single run resolves git, fetches every repository concurrently from the forge (GitHub, GitLab, Gitea, Forgejo, Codeberg or Bitbucket), optionally lets you pick a subset interactively, then dispatches clone / smart-sync / skip decisions across a worker pool. Smart sync consults a per-repository .corral-state.json sidecar to skip a git pull when the upstream pushed_at is unchanged.

graph TD

A[User Shell] --> B{corralctl} B --> C[Pre-flight: exec.LookPath git] C -- Missing --> Z1[Exit: git not found on PATH] C -- OK --> D[Resolve auto/token/gh auth] D --> E[Forge API: list repos] E --> E1["First page

• resp.LastPage"] E1 --> E2{LastPage > 1?} E2 -- Yes --> E3["Concurrent fetch

pages 2..N (max 5)"] E2 -- No --> F E3 --> F[Filtered repository set] F --> F1{TUI selector?} F1 -- "--select" --> F2[Interactive TUI /sort, /all, /none, search] F1 -- No --> G F2 --> G[Layout template render Collection/Bucket/Name] G --> H["Worker pool (--concurrency)"] H --> I{Already cloned?} I -- No --> J["git clone (+ blobless/ depth/single-branch)"] I -- "Yes (--no-sync)" --> K[SKIP] I -- Yes --> L{Smart sync: pushed_at advanced?} L -- No --> M[SKIP up-to-date] L -- "Yes (or --force-sync)" --> LG{"Operation in progress, local commits ahead, or no upstream?"} LG -- Yes --> LR[ERROR: pull refused] LG -- No --> N[git pull --rebase --autostash] N --> N1["+ optional submodule update (--ignore-submodule-failures)"] J & N1 --> O[Stamp .corral-state.json] O & K & M & LR --> P{All workers done?} P -- No --> H P -- Yes --> Q[Cleanup empty legacy dirs] Q --> R{--orphans?} R -- Yes --> S[Walk baseDir parse .git/config] R -- No --> T[Print summary] S --> T

---

Interactive TUI Mode

By passing the -i or --interactive flag, you can launch the selection dashboard:

./corralctl -i my-username

Keybindings

• [space] — Toggle selection of the current repository.
• [ctrl+a] — Select all currently filtered repositories.
• [ctrl+n] — Deselect all currently filtered repositories.
• [/] — Enter command / filter mode.
• [enter] — Confirm selection and begin cloning/syncing.
• [esc] — Exit the application silently.

In-Session Commands

Press / inside the TUI to enter Command Mode. Commands s