Python Package

The repos Python package wraps the same Bash scripts used by the command-line tool, so every feature available at the terminal is also available from Python.

The package ships its own bundled copy of the CLI scripts, so all Python functions work without requiring repos to be installed on your system PATH.

Installation

pip install git+https://github.com/MiguelRodo/repos.git

Or from a local clone:

git clone https://github.com/MiguelRodo/repos.git
cd repos
pip install .

System requirements: bash, git, curl, and jq must be available on your PATH. On Windows, use Git for Windows or WSL.

End-to-End Workflow

Step 1 — Create a `repos.list` file

Place a repos.list file in your project directory listing the repositories you want to manage (one per line):

myorg/data-curation
myorg/analysis
myorg/documentation

See the repos.list reference for the full syntax — branch pinning, worktrees, visibility flags, and more.

Step 2 — Clone repositories

from repos import run_script

run_script("helper/clone-repos.sh")

This reads repos.list and clones everything to the parent directory of your current location.

Step 3 — Open in your IDE (optional)

Generate a VS Code multi-root workspace file:

from repos import workspace

workspace()

Step 4 — Run a pipeline

Once the repositories are cloned, run a script inside each one:

from repos import run

run()          # executes run.sh in every repo

See run() below for all options.

API Reference

`install_cli()`

Print OS-appropriate instructions for installing the repos CLI globally, and optionally run the installer.

from repos import install_cli

install_cli(
    run=False  # if True, run the installer automatically
)

Parameters

Parameter	Type	Default	Description
`run`	`bool`	`False`	If `True`, attempt to run the installer automatically

Details

The Python package uses its own bundled copy of the CLI for all Python functions. However, if you also want to use repos directly from your terminal, this function installs the CLI system-wide. On Linux and macOS, passing run=True will also execute the installer. On Windows, only instructions are printed.

Returns: None

Examples:

from repos import install_cli

# Print installation instructions for your OS
install_cli()

# Print instructions AND run the installer
install_cli(run=True)

`bundled_cli_version()`

Return the version of the repos CLI bundled inside this package.

from repos import bundled_cli_version

bundled_cli_version()

Returns: str — the bundled CLI version string (e.g. "1.1.0").

Examples:

from repos import bundled_cli_version

print(bundled_cli_version())  # e.g. "1.1.0"

`installed_cli_version()`

Return the version of the repos CLI installed on the system PATH, or None if not found.

from repos import installed_cli_version

installed_cli_version()

Returns: str or None — the system-installed CLI version, or None.

Examples:

from repos import installed_cli_version

ver = installed_cli_version()
if ver is None:
    print("repos CLI is not installed on this system.")
else:
    print(f"Installed CLI version: {ver}")

`workspace()`

Generate or update the VS Code multi-root workspace file.

from repos import workspace

workspace(
    file=None,            # path to a custom list file (default: repos.list)
    debug=False,          # write debug output to stderr
    debug_file=None,      # write debug output to a file (True = auto-name, or pass a path)
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`debug`	`bool`	`False`	Print debug output to stderr
`debug_file`	`bool` or `str`	`None`	Write debug output to a file

Returns: subprocess.CompletedProcess

Examples:

from repos import workspace

# Generate workspace from default repos.list
workspace()

# Use a custom list file
workspace(file="my-repos.list")

For the full description, see the VS Code integration guide.

`codespace()`

Configure GitHub Codespaces authentication.

from repos import codespace

codespace(
    file=None,            # path to a custom list file (default: repos.list)
    devcontainer=None,    # path(s) to devcontainer.json (str or list[str])
    permissions=None,     # "all" or "contents" — passed to codespaces-auth-add.sh
    tool=None,            # force tool for codespaces-auth-add.sh ("jq" or "python")
    debug=False,          # write debug output to stderr
    debug_file=None,      # write debug output to a file (True = auto-name, or pass a path)
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`devcontainer`	`str` or `list[str]`	`None`	Path(s) to `devcontainer.json`
`permissions`	`str`	`None`	`"all"` or `"contents"`
`tool`	`str`	`None`	Force `"jq"` or `"python"` for auth helper
`debug`	`bool`	`False`	Print debug output to stderr
`debug_file`	`bool` or `str`	`None`	Write debug output to a file

Returns: subprocess.CompletedProcess

Examples:

from repos import codespace

# Configure with default devcontainer path
codespace()

# Specify a devcontainer.json path
codespace(devcontainer=".devcontainer/devcontainer.json")

# Multiple devcontainer paths
codespace(devcontainer=[".devcontainer/devcontainer.json",
                        ".devcontainer/prebuild/devcontainer.json"])

For the full description, see the VS Code integration guide.

`run()`

Execute a script inside each cloned repository.

from repos import run

run(
    file=None,              # path to a custom list file (default: repos.list)
    script=None,            # script to run in each repo (default: run.sh)
    include=None,           # repo name(s) to include
    exclude=None,           # repo name(s) to skip
    ensure_setup=False,     # run setup() before executing scripts
    skip_deps=False,        # skip install-r-deps.sh
    dry_run=False,          # print what would run without executing
    verbose=False,          # verbose logging
    continue_on_error=False # keep running after a failure
)

Parameters

Parameter	Type	Default	Description
`file`	`str`	`None`	Path to repos list file (default: `repos.list`)
`script`	`str`	`None`	Script file to run in each repo (default: `run.sh`)
`include`	`str` or `list[str]`	`None`	Only run in these repos
`exclude`	`str` or `list[str]`	`None`	Skip these repos
`ensure_setup`	`bool`	`False`	Clone repos first (via `repos clone`)
`skip_deps`	`bool`	`False`	Skip R dependency installation
`dry_run`	`bool`	`False`	Preview without executing
`verbose`	`bool`	`False`	Verbose logging
`continue_on_error`	`bool`	`False`	Continue past failures

Returns: subprocess.CompletedProcess

Examples:

from repos import run

# Run the default script (run.sh) in every repo
run()

# Run a custom script
run(script="build.sh")

# Only run in specific repos
run(include=["backend", "frontend"])

# Skip a repo
run(exclude="docs")

# Continue even if one repo fails
run(continue_on_error=True)

# Preview without running
run(dry_run=True)

# Ensure repos are cloned before running
run(ensure_setup=True)

# Combine options
run(script="test.sh", verbose=True, ensure_setup=True)

For the full behavioural description, see Running Pipelines.

Raw argument passing

If you need to pass flags not yet exposed as keyword arguments, use the raw helpers:

from repos import workspace_raw, codespace_raw, run_raw

workspace_raw("-f", "custom.list")

codespace_raw("-d", ".devcontainer/devcontainer.json")

run_raw("--script", "build.sh", "--dry-run")
run_raw("-f", "custom.list", "--continue-on-error")

These functions forward all positional arguments directly to the underlying Bash script without any processing.

GitHub Authentication

codespace() needs a GitHub token with Codespaces permissions. Provide it via the GH_TOKEN environment variable or via the gh CLI:

import os, subprocess
from repos import codespace

os.environ["GH_TOKEN"] = "your_personal_access_token"
codespace()

Or in a shell before starting Python:

export GH_TOKEN="your_personal_access_token"
python my_script.py

Bundled CLI vs. System CLI

The Python package ships a bundled copy of the Bash scripts that it uses for all Python functions (run(), workspace(), etc.). This bundled version is independent of any repos binary you may have installed on your system PATH.

You can inspect both versions at any time:

from repos import bundled_cli_version, installed_cli_version

print("Bundled:", bundled_cli_version())
print("System: ", installed_cli_version())  # None if not installed

Does installing the Python package also install the `repos` CLI?

No. Installing the package via pip does not place a repos command on your system PATH. All Python functions work immediately through the package’s own bundled scripts, but you will need to install the CLI separately if you also want to use repos directly from a terminal.

The easiest way is to call install_cli() from Python:

from repos import install_cli

# Print OS-appropriate installation instructions
install_cli()

# Or print instructions AND run the installer automatically
install_cli(run=True)

See install_cli() above for details, or visit the Installation guide for all options.

Installation

End-to-End Workflow

Step 1 — Create a repos.list file

Step 2 — Clone repositories

Step 3 — Open in your IDE (optional)

Step 4 — Run a pipeline

API Reference

install_cli()

bundled_cli_version()

installed_cli_version()

workspace()

codespace()

run()

Raw argument passing

GitHub Authentication

Bundled CLI vs. System CLI

Does installing the Python package also install the repos CLI?

Step 1 — Create a `repos.list` file

`install_cli()`

`bundled_cli_version()`

`installed_cli_version()`

`workspace()`

`codespace()`

`run()`

Does installing the Python package also install the `repos` CLI?