CLI reference

The repo-management command drives a YAML config against GitHub: validate it offline, preview the diff, or apply it.

validate

repo-management validate -c CONFIG

Validates the config file without contacting GitHub — no network access. Use it to catch schema errors before you need a token.

--config / -c: Path to the YAML config file. Required.

On success:

✓ {config} is valid ({n} repo(s))

plan

repo-management plan -c CONFIG [--repo owner/name] [--token TOKEN] [--force-secrets]

Read-only. Computes the diff between the config and each repo's current state on GitHub, and prints it without writing anything.

--config / -c: Path to the YAML config file. Required.
--repo / -r: Limit the run to a single owner/name repo from the config. Errors if the repo isn't in the config.
--token: GitHub token to authenticate with. default: $GITHUB_TOKEN
--force-secrets: Re-push existing secret values, as if rotating them. By default, secrets already present on the repo are left untouched.

Output

For each repo, either it's already in sync:

✓ {repo}: in sync

or it lists the pending changes, one indented line per change:

{repo} — {n} change(s):
  + [domain] target = value
  ~ [domain] target: before -> after
  - [domain] target (was value)

+ marks a create, ~ an update, - a delete. The run ends with a summary line:

{total} change(s) across {n} repo(s).

Secret values are always redacted in output, regardless of --force-secrets. Variable values are shown in plaintext, so don't put anything sensitive in a variables: entry — use a secret instead.

apply

repo-management apply -c CONFIG [--repo owner/name] [--token TOKEN] [--force-secrets] [--yes]

Applies the same diff plan would show. Prints the plan first, then writes the changes to GitHub.

--config / -c: Path to the YAML config file. Required.
--repo / -r: Limit the run to a single owner/name repo from the config. Errors if the repo isn't in the config.
--token: GitHub token to authenticate with. default: $GITHUB_TOKEN
--force-secrets: Re-push existing secret values, as if rotating them. By default, secrets already present on the repo are left untouched.
--yes / -y: Skip the confirmation prompt.

If every repo is already in sync, it prints nothing to do and exits without prompting. Otherwise, unless --yes is given, it asks:

Apply {total} change(s)?

Declining the prompt exits with error: aborted and applies nothing.

On success:

✓ applied {n} change(s)

list-repos

repo-management list-repos [--config-dir DIR] [--format lines|names]

Lists the managed-repo fleet: the union of the repos: lists across every applied *.yml file in the config directory. *.yaml files are treated as extends-only base layers and skipped. No network access.

--config-dir: Directory of applied config files to scan. default: config
--format / -f: Output shape: lines or names. default: lines

Formats

Format	Output
`lines`	One `owner/repo` per line.
`names`	A single comma-separated line of bare repo names, with the owner stripped. Requires the fleet to have a single owner — errors otherwise.

names output is sized for scoping a GitHub App token's repositories: list to exactly the fleet. Output is plain stdout — no styling or line wrapping — so it's safe to pipe or capture in a narrow terminal.

Global behavior

Authentication

Commands that talk to GitHub (plan, apply) need a token, from --token or the $GITHUB_TOKEN environment variable. The token needs scopes covering whatever the config manages on the target repos. validate and list-repos never contact GitHub and don't need a token.

Errors

All errors print to stderr as error: {message} and exit with status 1. Errors returned by the GitHub API surface as:

error: GitHub API error: {detail}