CLI Reference

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli.rs
• src/main.rs
• src/sync.rs
• src/config.rs
• README.md
• action.yml
• AGENTS.md

The orcastrate CLI manages GitHub Actions workflows across multiple repositories from a central orchestrator repository. It allows developers to render templates, detect configuration drift, and synchronize workflow files using Pull Requests or GitHub Issues.

High-Level Execution Flow

The CLI follows a standard pattern of parsing arguments, loading a central configuration file, initializing the GitHub client with appropriate credentials, and dispatching logic to specific command handlers.

---

Global Options

Global options apply to all subcommands and control the general behavior of the tool, such as logging verbosity and configuration paths.

Option	Alias	Description	Default
--config <PATH>	-c	Path to the orchestrator.toml configuration file.	orchestrator.toml
--dry-run	--dry	Simulates operations without modifying remote files or opening PRs.	false
-v, -vv, -q	N/A	Controls log verbosity (Info, Debug, Trace, or Quiet).	Info

Sources: src/cli.rs:17-27, README.md:95-97

---

Command Reference

sync

Synchronizes workflows across configured repositories. It scans repositories for managed blocks, renders templates, and applies changes based on the selected mode.

• Flags:
  • --repo <REPO>: Limits synchronization to a single repository (format: owner/name).
  • --mode <pr|issue|silent>: Determines how drift is handled.
    • pr: Opens/updates a Pull Request for every drifted workflow.
    • issue: Opens/updates a GitHub Issue for every drifted workflow.
    • silent: Reports drift without taking remote action.

Sources: src/cli.rs:35-41, src/sync.rs:234-299

drift

An alias for sync --mode silent. It checks for differences between local templates and remote workflows without creating PRs or issues.

Sources: src/cli.rs:65-68, src/main.rs:65

validate

Performs a local check of the orchestrator.toml file and all templates in the configured templates directory. It ensures that the configuration is syntactically correct and that templates can be loaded by the Tera engine.

Sources: src/cli.rs:44, src/main.rs:81-96

render

Renders a specific local workflow file containing @orcastrate frontmatter to standard output. This is used to test parameter injection and template rendering without needing GitHub credentials or connectivity.

• Arguments:
  • <workflow>: The path to the local YAML file to render.

Sources: src/cli.rs:47, src/main.rs:52-57

list-repos

Displays all repositories currently managed by the orchestrator. This includes repositories explicitly defined in [[repos]] and those discovered via the [discovery] configuration.

Sources: src/cli.rs:50, src/main.rs:98-116

list-templates

Lists all available Tera templates found in the templates_dir defined in the configuration.

Sources: src/cli.rs:53, src/main.rs:118-127

---

Authentication Configuration

The CLI requires authentication to interact with the GitHub API. It supports three authentication methods, prioritized as follows:

1. GitHub App: Requires ORCASTRATE_APP_ID, ORCASTRATE_PRIVATE_KEY, and ORCASTRATE_INSTALLATION_ID.
2. Personal Access Token (PAT): Uses ORCASTRATE_TOKEN.
3. Default Actions Token: Uses GITHUB_TOKEN.

Dual-Token Pattern

When using ORCASTRATE_TOKEN for workflow writes, the CLI also requires GITHUB_TOKEN to handle Pull Request operations. This ensures that PRs are authored by the GitHub Actions bot while sensitive workflow changes are authorized by the PAT.

---

Output and Reporting

When running sync or drift, the CLI produces a summary report. If executed within a GitHub Actions environment, it also generates a Step Summary in Markdown.

Report Fields

• Repos processed: Total number of repositories checked.
• Workflows checked: Total workflow files scanned.
• Managed workflows: Files containing the @orcastrate marker.
• Drifted: Number of workflows where the rendered template differs from the remote file.
• Errors: List of failures (e.g., render errors, API timeouts).

Sources: src/sync.rs:25-75, src/main.rs:72-73

---

Summary

The orcastrate CLI serves as the engine for automated workflow management. By providing commands for both local validation (render, validate) and remote synchronization (sync, drift), it enables a safe development lifecycle for organization-wide GitHub Actions configurations. The tool is designed for headless execution in CI/CD but maintains robust human-readable feedback through its reporting system.