Corral

Automatically clone and organise GitHub repositories by visibility and language.

Install

Homebrew (macOS / Linux):

brew install sebastienrousseau/tap/corralctl

Arch Linux (AUR):

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

From source (requires Go 1.26+):

git clone https://github.com/sebastienrousseau/corral.git
cd corral
make build              # produces ./corralctl
gh auth login
./corralctl <owner>

Prebuilt binaries and .deb/.rpm packages are also attached to each GitHub release.

Then verify the output:

ls ~/Code/

Requires gh, git, and Go 1.26+. Works on macOS, Ubuntu/Debian, Fedora/RHEL, Arch, and WSL2.

The command is corralctl (the project is Corral); the …ctl binary name avoids a clash with the unrelated corral formula in homebrew-core.

brew install go git gh

sudo apt install golang git

sudo dnf install golang git gh

# crontab -e
0 2 * * * /path/to/corralctl my-username

Overview

Most cloning tools dump every repository into a single flat directory. Finding anything means scrolling through hundreds of folders with no structure. Corral creates a clean, navigable local mirror — sorted by visibility and language — in one command. No config files.

~/Code/
├── Public/
│   ├── rust/
│   │   └── my-crate/
│   ├── typescript/
│   │   └── my-app/
│   └── other/
│       └── dotfiles/
└── Private/
    └── python/
        └── internal-tool/

• One command to clone and organise every repository from a user or organisation
• Safe to re-run at any time — new repos are cloned, and existing ones are pulled to their latest changes (unless --no-sync is passed)
• Automatic migration from flat ~/Code/<Language>/ layouts to the new visibility-based structure
• Tested on macOS and Ubuntu with automated tests, 100% coverage, and signed commits.

Architecture

Run once or a hundred times, the directory tree converges on the same state.

graph TD
    A[User Shell] --> B{Corral}
    B --> C[Pre-flight: Git / GitHub API]
    C -- Missing --> Z1[Exit: dependency error]
    C -- OK --> D[GitHub API → Fetch Repos]
    D -- Fails --> Z2[Exit: API error]
    D -- OK --> E[Loop: each repo]
    E --> F{Already cloned?}
    F -- "Yes (default)" --> G1[git pull --rebase --autostash]
    F -- "Yes + --no-sync" --> G2[Skip]
    F -- No --> H{Legacy directory?}
    H -- Yes --> I[Migrate to new layout]
    H -- No --> J[git clone]
    G1 & G2 & I & J --> E
    E -- Done --> K[Remove empty legacy directories]
    K --> L[Print summary]

Features

Usage

Clone a personal account:

./corralctl my-username

Clone an organisation into a custom directory:

./corralctl my-org ~/Projects 500

Clone via SSH (key-based auth):

./corralctl --protocol ssh my-username

Skip pulling updates for existing clones:

./corralctl --no-sync my-username

Preview what would happen without making changes:

./corralctl --dry-run my-org

Fetch only private Go and Rust repositories, and emit machine-readable JSON:

./corralctl --visibility private --languages go,rust --output json my-org

Use GitHub CLI auth explicitly and perform shallow single-branch clones:

./corralctl --auth gh --clone-single-branch --clone-depth 1 my-username

Detect local repositories that no longer exist on GitHub (orphans):

./corralctl --orphans my-username

Clone with submodules, raising concurrency for a large account:

./corralctl --recurse-submodules --concurrency 16 my-org

Include forks and archived repositories, excluding generated languages:

./corralctl --include-forks --include-archived --exclude-languages makefile,dockerfile my-username

Stream one NDJSON record per repository (ideal for piping into jq):

./corralctl --output ndjson my-org | jq -r 'select(.action=="CLONE") | .repo'

Use a fixed token and tune retry backoff for flaky networks:

GITHUB_TOKEN=ghp_xxx ./corralctl --auth token --retry-max 6 --retry-min-backoff 1s --retry-max-backoff 30s my-org

Print the version:

./corralctl --version

By default (--auth auto), Corral checks GITHUB_TOKEN/GH_TOKEN first, then falls back to gh auth token.

What's Included

For security policy and vulnerability reporting, see SECURITY.md.

THE ARCHITECT ᛫ Sebastien Rousseau THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

License

Licensed under the GNU General Public License v3.0.

Back to Top