Command Line Interface

The pygha.cli module exposes a pygha console script with sub-commands for initializing and building pipelines.

Options

--version

Show the version number and exit.

Commands

init

Scaffolds a new pygha project by creating a sample pipeline file.

$ pygha init                    # Creates .pipe/ci_pipeline.py
$ pygha init --src-dir custom   # Creates custom/ci_pipeline.py

The generated ci_pipeline.py includes a minimal working configuration:

from pygha import job, default_pipeline
from pygha.steps import run, checkout

default_pipeline(on_push=["main"], on_pull_request=True)

@job
def build():
    checkout()
    run("pip install .")
    run("pytest")

Options

--src-dir

Defaults to .pipe. The directory where the sample pipeline file will be created.

build

Scans a source directory for pipeline files, executes them to populate the registry, and transpiles each registered pipeline to GitHub Actions YAML.

$ pygha build --src-dir .pipe --out-dir .github/workflows --clean

Options

--src-dir

Defaults to .pipe. Every file matching pipeline_*.py or *_pipeline.py in this directory is executed with runpy.

--out-dir

Defaults to .github/workflows. For each registered pipeline a <name>.yml file is written using pygha.transpilers.github.GitHubTranspiler.

--clean

Deletes orphaned YAML files from the output directory unless they start with # pygha: keep within the first ten lines. This is a useful safety valve when rotating pipelines.

Exit status

Returns 0 even when no pipelines were registered so the command is safe to run in empty repositories. Any exception raised while executing a pipeline file or running the transpiler will propagate to the caller, giving CI runners immediate feedback.