CLI Reference

Complete reference for all common-repo commands.

Global Options

These options are available for all commands:

Verbosity Control

The --verbose and --quiet flags provide convenient shortcuts for controlling output verbosity:

• --quiet: Shows only error messages. Useful for scripting.
• --verbose: Shows debug-level messages. Can be repeated for more detail.
• --verbose --verbose: Shows trace-level messages (maximum verbosity).

These flags override --log-level when specified. Note that --verbose and --quiet cannot be used together.

Examples:

# Minimal output for scripts
common-repo apply --quiet

# Debug output to troubleshoot issues
common-repo apply --verbose

# Maximum verbosity for detailed debugging
common-repo check --verbose --verbose

Commands

add - Add Repository

Add a repository to an existing .common-repo.yaml configuration file. Automatically detects the latest semver tag.

common-repo add [OPTIONS] <URI>

Arguments

Options

Examples

# Add a repo to existing config
common-repo add your-org/shared-configs

# Add using full URL
common-repo add https://github.com/your-org/shared-configs

# Create new config with --yes (non-interactive)
common-repo add --yes your-org/shared-configs

Behavior

• If .common-repo.yaml exists: appends the new repository before the include section
• If no config exists: prompts for confirmation to create a minimal config (use --yes to skip prompt)
• Automatically fetches and uses the latest semver tag, or falls back to main if no tags found
• Warns when adding repositories with only 0.x.x versions (unstable API)

apply - Apply Configuration

Apply the .common-repo.yaml configuration to your repository. This runs the full 6-phase pipeline: discover repos, clone, process, merge, and write files.

common-repo apply [OPTIONS]

Options

Use global --verbose or --quiet flags for verbosity control.

Examples

# Apply configuration
common-repo apply

# Preview changes without applying
common-repo apply --dry-run

# Apply with verbose output
common-repo apply --verbose

# Apply to a different directory
common-repo apply --output ./output

# Force fresh clones (ignore cache)
common-repo apply --no-cache

# Use a different config file
common-repo apply --config my-config.yaml

check - Validate and Check Updates

Check configuration validity and optionally check for repository updates.

common-repo check [OPTIONS]

Options

Examples

# Validate configuration
common-repo check

# Check for available updates
common-repo check --updates

Output

When checking for updates, you’ll see:

• Current ref for each inherited repo
• Available newer versions (if any)
• Whether updates are compatible (minor/patch) or breaking (major)

completions - Generate Shell Completions

Generate shell completion scripts for tab-completion support.

common-repo completions <SHELL>

Arguments

Examples

# Generate bash completions
common-repo completions bash > ~/.local/share/bash-completion/completions/common-repo

# Generate zsh completions
common-repo completions zsh > ~/.zfunc/_common-repo

# Generate fish completions
common-repo completions fish > ~/.config/fish/completions/common-repo.fish

# Generate PowerShell completions
common-repo completions powershell >> $PROFILE

Installation

Bash

# Option 1: User-level installation
mkdir -p ~/.local/share/bash-completion/completions
common-repo completions bash > ~/.local/share/bash-completion/completions/common-repo

# Option 2: Source directly in .bashrc
echo 'eval "$(common-repo completions bash)"' >> ~/.bashrc

Zsh

# Add to fpath (recommended)
mkdir -p ~/.zfunc
common-repo completions zsh > ~/.zfunc/_common-repo

# Add to .zshrc (before compinit)
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

Fish

common-repo completions fish > ~/.config/fish/completions/common-repo.fish

PowerShell

# Add to your PowerShell profile
common-repo completions powershell >> $PROFILE

Elvish

common-repo completions elvish >> ~/.elvish/rc.elv

Note on cr alias: If you installed via the shell installer, the cr alias is available. Completions generated for common-repo will work when you type common-repo. For the cr alias, you can create a symlink or alias in your shell configuration, or generate completions separately using cr completions <shell>.

diff - Preview Changes

Show differences between current files and what the configuration would produce.

common-repo diff [OPTIONS]

Options

Examples

# Show full diff
common-repo diff

# Show summary only
common-repo diff --summary

# Compare against a different directory
common-repo diff --working-dir ./other-project

init - Initialize Configuration

Create a new .common-repo.yaml configuration file. By default, launches an interactive wizard that guides you through adding repositories with automatic version detection.

common-repo init [OPTIONS] [URI]

Arguments

Options

Examples

# Launch interactive wizard (default)
common-repo init

# Initialize from a specific repository
common-repo init https://github.com/your-org/shared-configs

# Use GitHub shorthand
common-repo init your-org/shared-configs

# Overwrite existing config
common-repo init --force

# Explicitly use interactive mode
common-repo init --interactive

Interactive Wizard

When run without arguments, init launches an interactive wizard that:

1. Prompts for repository URLs (supports GitHub shorthand like org/repo)
2. Auto-detects the latest semver tag for each repository
3. Falls back to main branch if no semver tags are found
4. Optionally sets up pre-commit hooks (detects prek or pre-commit CLI)
5. Generates a ready-to-use .common-repo.yaml

update - Update Repository Refs

Update repository refs in your configuration to newer versions.

common-repo update [OPTIONS]

Options

Examples

# Update to latest compatible versions (minor/patch only)
common-repo update

# Preview updates without applying
common-repo update --dry-run

# Update to latest versions including breaking changes
common-repo update --latest

# Update without confirmation
common-repo update --yes

info - Show Configuration Info

Display information about the current configuration.

common-repo info [OPTIONS]

Options

Examples

# Show configuration overview
common-repo info

Output

Shows:

• Inherited repositories and their refs
• Operations defined
• Template variables
• Required tools

ls - List Files

List files that would be created or modified by the configuration.

common-repo ls [OPTIONS]

Options

Examples

# List all files
common-repo ls

# Long format
common-repo ls -l

# Filter by pattern
common-repo ls --pattern "*.yml"
common-repo ls -p "src/**/*.rs"

# Count files
common-repo ls --count

# Sort by size, largest first
common-repo ls -l --sort size --reverse

validate - Validate Configuration

Validate a .common-repo.yaml configuration file for syntax and semantic errors.

common-repo validate [OPTIONS]

Options

Examples

# Validate syntax
common-repo validate

# Also check that repos are accessible
common-repo validate --check-repos

# Strict mode (fail on warnings)
common-repo validate --strict

cache - Manage Cache

Manage the repository cache.

common-repo cache <SUBCOMMAND> [OPTIONS]

Global Cache Options

Subcommands

list - List cached repositories

common-repo cache list [OPTIONS]

clean - Clean cached repositories

common-repo cache clean [OPTIONS]

At least one filter must be specified:

Duration format: Number followed by unit: s (seconds), m (minutes), h (hours), d (days), w (weeks). Examples: 30d, 7d, 1h, 2w, 30days, 1week

Examples

# List all cached repos
common-repo cache list

# List with detailed info
common-repo cache list --detailed

# Output as JSON for scripting
common-repo cache list --json

# Preview what would be cleaned (dry run)
common-repo cache clean --unused --dry-run

# Delete entries older than 30 days
common-repo cache clean --unused

# Delete entries older than 7 days
common-repo cache clean --older-than 7d

# Delete all cached repos without prompting
common-repo cache clean --all --yes

JSON Output Schema

When using cache list --json, the output format is:

[
  {
    "hash": "a1b2c3d4",
    "ref": "v1.0.0",
    "path": "subdir or null",
    "size": 12345,
    "file_count": 42,
    "last_modified": 1704067200
  }
]

tree - Show Inheritance Tree

Display the repository inheritance tree.

common-repo tree [OPTIONS]

Options

Examples

# Show full inheritance tree
common-repo tree

# Show only first two levels
common-repo tree --depth 2

Output

my-project
├── github.com/common-repo/rust-cli@v2.0.0
│   └── github.com/common-repo/base@v1.0.0
└── github.com/common-repo/pre-commit@v1.5.0

Environment Variables

Exit Codes

Special case for diff command:

• Exit code 0: No changes detected (files match configuration)
• Exit code 1: Changes detected (files differ from configuration)

This follows the convention established by diff(1) and git diff.

Scripting examples:

# Check if config is valid
common-repo validate && echo "Config is valid"

# Check if changes are needed
common-repo diff && echo "Up to date" || echo "Changes detected"

# Handle usage errors separately from runtime errors
common-repo apply
case $? in
  0) echo "Success" ;;
  1) echo "Error during execution" ;;
  2) echo "Invalid arguments" ;;
esac

Common Workflows

First-Time Setup

# Initialize config interactively
common-repo init

# Or add repos one at a time
common-repo add your-org/shared-configs
common-repo add your-org/ci-templates

# Preview what would be created
common-repo ls
common-repo diff

# Apply
common-repo apply

Regular Maintenance

# Check for updates
common-repo check --updates

# Review and apply updates
common-repo update --dry-run
common-repo update

Shell Completions

Enable tab-completion for faster command entry:

# Bash
common-repo completions bash > ~/.local/share/bash-completion/completions/common-repo

# Zsh
common-repo completions zsh > ~/.zfunc/_common-repo

# Fish
common-repo completions fish > ~/.config/fish/completions/common-repo.fish

See completions for detailed installation instructions.

Debugging

# Debug output
common-repo apply --verbose

# Maximum verbosity (trace level)
common-repo apply --verbose --verbose

# Validate configuration
common-repo validate --check-repos --strict

# View inheritance
common-repo tree
common-repo info