gh-flarebyte

Use gh flarebyte to keep a GitHub repository aligned with the config checked into the repo.

What it does

gh-flarebyte is a GitHub CLI extension for managing a repository from a local .gh-flarebyte.cue file. It helps you:

• bootstrap a repository config
• update repo settings from config
• audit drift between config and GitHub
• sync topics and labels from config
• build binary artifacts, library compile checks, Python distributions, or Rust crate packages
• publish a GitHub release with or without build artifacts
• discover repositories you contribute to in an organization

Commands

Repo sync

• gh flarebyte repo init --repo <owner/name> [--overwrite] creates or seeds .gh-flarebyte.cue for a repository.
• gh flarebyte repo update [--repo <owner/name>] [--confirm-deletions] [--accept-visibility-change-consequences] applies the repo config to GitHub.
• gh flarebyte repo audit [--repo <owner/name>] [--json] compares the local config with the live GitHub repository.
• gh flarebyte repos mine --org <org> lists repositories you contribute to in an organization.

Build and release

• gh flarebyte build [--target <os-arch>] [--output-dir <path>] builds the project using the language and mode defined in .gh-flarebyte.cue.
• gh flarebyte release [--draft] [--notes-file <path>] builds first, then publishes a GitHub release from the configured release policy.
• build: Go supports binary and library; Dart supports library; Python 3 with uv supports package; Rust supports all three modes.
• release: Dart currently supports release with release.includeArtifacts: false.

Dev commands

• gh flarebyte test [--style summary|per_test] [--color auto|true|false] [--failed-only] runs tests for the configured build language, with optional per-invocation output overrides.
• gh flarebyte format formats source files for the configured build language.
• gh flarebyte lint [--color auto|true|false] [--failed-only] runs lint/static checks for the configured build language.
• gh flarebyte cov [--min <percent>] [--color auto|true|false] [--failed-only] computes coverage and can fail below a threshold.

Runtime info

• gh flarebyte --version prints the CLI version metadata, including version, commit id, build date, OS/arch, and Go runtime version.
• gh flarebyte --version --json prints the same version metadata in a machine-readable JSON shape.

Use gh flarebyte --help for command usage. Error output is designed to include the failing config field or target and a practical next step.

Config

The repo config lives in .gh-flarebyte.cue and is the source of truth for:

• repository metadata such as description, homepage, visibility, and template status
• topics
• labels
• repository feature flags currently enforced by sync/audit: repository.features.mergeCommit, repository.features.rebaseMerge, repository.features.squashMerge, repository.features.deleteBranchOnMerge
• build language, mode, and artifact policy
• go command execution env for dev flows (go.cacheDir, go.modCacheDir, go.toolchain)
• go build CGO contract (go.cgo.enabled, go.cgo.cc, go.cgo.cxx)
• dev command output controls (devOutput.color, devOutput.style, devOutput.showPassed)
• coverage threshold policy (coverage.min, coverage.enforceMin)
• release settings
• additional repository feature fields may exist in config but are not yet enforced by repo update / repo audit

Example:

project: {
  org:  "flarebyte"
  repo: "gh-flarebyte"
}

repository: {
  description: "CLI for landing your git commands right"
  defaultBranch: "main"
  topics: ["gh-extension", "github-cli", "git", "flarebyte"]
  labels: [
    {
      name: "bug"
      color: "B60205"
      description: "Something is broken"
    },
  ]
}

build: {
  language: "go"
  mode: "binary"
  outputDir: "build"
  checksumFile: "build/checksums.txt"
  artifactTargetSuffix: true
  targets: ["linux-amd64", "darwin-arm64"]
}

go: {
  cacheDir: "./.gocache"
  modCacheDir: "./.gomodcache"
  toolchain: "local"
  cgo: {
    enabled: true
    cc: "clang"
    cxx: "clang++"
  }
}

devOutput: {
  color: "auto"
  style: "summary"
  showPassed: true
}

coverage: {
  min: 80
  enforceMin: true
}

release: {
  versionSource: "main.project.yaml"
  tagPrefix: "v"
  notesMode: "generate-notes"
  includeArtifacts: true
  artifactDir: "build"
  includeChecksums: true
}

Go library example:

build: {
  language: "go"
  mode: "library"
  packages: ["./..."]
  runTests: true
}

release: {
  versionSource: "main.project.yaml"
  tagPrefix: "v"
  notesMode: "generate-notes"
  includeArtifacts: false
}

Dart library example:

build: {
  language: "dart"
  mode:     "library"
  packages: ["./..."]
  runTests: true
}

coverage: {
  min: 80
  enforceMin: true
}

release: {
  versionSource: "main.project.yaml"
  tagPrefix: "v"
  notesMode: "generate-notes"
  includeArtifacts: false
}

Python package example (reuse the same repository configuration as Go or Dart):

build: {
  language: "python"
  mode: "package"
  runTests: true
  outputDir: "build"
  checksumFile: "build/checksums.txt"
}

devOutput: {
  color: "auto"
  style: "summary"
  showPassed: true
}

coverage: {
  min: 80
  enforceMin: true
}

release: {
  versionSource: "pyproject.toml"
  tagPrefix: "v"
  notesMode: "generate-notes"
  artifactDir: "build"
  includeArtifacts: true
  includeChecksums: true
}

Install uv and declare Python support with [project].requires-python in pyproject.toml. Use .python-version if you want to pin the interpreter. Add the developer tools with uv add --dev pytest ruff coverage, configure their rules in pyproject.toml, and commit uv.lock. Commands run through uv run --locked: uv may install the locked dependencies into .venv, but a missing or stale lockfile fails rather than being updated. Missing tools are reported as failures.

test uses pytest JUnit XML for summaries and per-test output. format uses Ruff formatting; lint uses Ruff checks without automatic fixes. cov runs pytest under coverage.py and applies the same coverage.min, coverage.enforceMin, and --min policy as Go and Dart. Configure [tool.coverage.run].source to include your package and measure untested modules.

build produces a wheel and source distribution using uv build --no-sources, plus SHA-256 checksums. Use an explicit [build-system] and pin its build dependencies for repeatable isolated builds; those dependencies are resolved separately from uv.lock. --output-dir relocates both distributions and the checksum manifest. release attaches only files from its fresh build, respecting release.artifactDir and release.includeChecksums; release.includeArtifacts: false publishes without assets.

Initial Python support covers one package per repository, with no binary mode, target matrix, or PyPI upload. Keep build.targets unset. Package filenames follow Python distribution naming, so build.artifactTargetSuffix does not apply. TOML version sources require a static [project].version following the existing semantic-version rule (for example 1.2.3). Dynamic versions and Python-specific versions such as 1.2.3rc1 are not supported yet.

Rust library example (reuse the same repository configuration and output/coverage settings):

build: {
  language: "rust"
  mode: "library"
  packages: ["./..."]
  runTests: true
}

coverage: { min: 80, enforceMin: true }
devOutput: { color: "auto", style: "summary", showPassed: true }

release: {
  versionSource: "Cargo.toml"
  tagPrefix: "v"
  notesMode: "generate-notes"
  includeArtifacts: false
}

Rust executable build block:

build: {
  language: "rust"
  mode: "binary"
  mainPackage: "."
  runTests: true
  outputDir: "build"
  checksumFile: "build/checksums.txt"
  artifactTargetSuffix: true
  targets: ["linux-amd64", "darwin-arm64"]
}

For .crate distributions, use mode: "package", packages: ["./..."], outputDir, and checksumFile, omitting targets. For executable or package releases, set release.includeArtifacts: true, release.artifactDir: "build", and optionally release.includeChecksums: true. All artifact-producing Rust builds honor --output-dir.

Install a stable Rust toolchain with rustfmt and Clippy. Keep toolchain selection in rust-toolchain.toml, Rust version/edition/lints in Cargo.toml, and Cargo configuration in .cargo/config.toml. Commit Cargo.lock at the workspace root. Dependency-resolving commands use --locked; a missing or stale lock fails without being rewritten. Formatting also requires a project manifest and an existing lockfile. Cargo may download locked dependencies and consult the registry during packaging.

test runs the whole workspace, including unit, integration, and documentation tests. Standard harness output supports summaries, per_test, ignored tests, and --failed-only. Custom harness = false targets support summary style only. format uses cargo fmt --all; lint uses Clippy across the workspace and all targets, treats warnings as errors, and does not fix code.

cov requires cargo-llvm-cov (cargo install cargo-llvm-cov --locked) and the active toolchain's llvm-tools-preview component (rustup component add llvm-tools-preview). It runs workspace tests and computes total line coverage from LCOV line counts, excluding sources outside the workspace and generated/dependency directories (target, .cargo, .cache, vendor). It uses isolated temporary coverage artifacts and the shared threshold/output settings. Stable coverage excludes doctests; ordinary test still runs them. Missing coverage components fail with installation guidance.

build.packages defaults to ["./..."], selecting all workspace members for library/package builds; explicit values are exact Cargo crate names. Developer commands operate on the whole workspace. Binary builds use build.mainPackage, the directory containing the package's Cargo.toml, defaulting to ".". The selected package must have one binary or declare package.default-run. Cargo compiler JSON identifies the executable, avoiding assumptions about Cargo's output filenames.

Library builds compile selected crates without release assets. Binary builds use Cargo's release profile and the same archive, binary naming, checksums, and target-suffix policy as Go. Package builds run verified cargo package --locked and produce one .crate per selected crate; Cargo's clean-source and registry packaging rules apply. build.runTests enables host tests of the selected crates before any build mode, including cross-compilation.

Rust preserves the shared target names with these mappings:

Target	Rust triple
linux-amd64	x86_64-unknown-linux-gnu
linux-arm64	aarch64-unknown-linux-gnu
darwin-amd64	x86_64-apple-darwin
darwin-arm64	aarch64-apple-darwin
windows-amd64	x86_64-pc-windows-msvc
windows-arm64	aarch64-pc-windows-msvc

Install the target components and suitable linkers before cross-building. --target filters binary targets or selects a library compile check; package mode rejects it. Custom triples and musl builds are outside the initial target mapping.

release.versionSource can point to a package's Cargo.toml, including workspace-inherited package.version. A virtual workspace manifest has no package release version: point to a member manifest instead. Releases use fresh build assets only, preserve subdirectories when staging into release.artifactDir, and support notes, drafts, and releases without assets. crates.io publishing is outside the initial scope.

Typical workflow

1. Run gh flarebyte repo init in a repo that should be managed.
2. Edit .gh-flarebyte.cue to match the desired repository state.
3. Run gh flarebyte repo update to sync the repo.
4. Run gh flarebyte repo audit to check for drift.
5. Run gh flarebyte build and gh flarebyte release when you are ready to ship.
6. Run gh flarebyte test, format, lint, and cov for local quality checks.

Makefile shortcuts

• make build-go builds the local CLI binary at .e2e-bin/gh-flarebyte.
• make release runs .e2e-bin/gh-flarebyte release (it depends on build-go).
• GH_FLAREBYTE_FAKE_RELEASE=1 make release runs the release flow in fake mode (no GitHub mutation).
• make review-dart runs format-dart, test-dart, lint-dart, and coverage-dart.
• make test-python-e2e runs the real uv fixture (requires uv and an installed Python 3; may download dependencies).
• make test-rust-e2e runs the real Rust workspace fixture (requires Cargo, rustfmt, Clippy, cargo-llvm-cov, and llvm-tools-preview; may access crates.io).

Language support snapshot

• Go:
  • build and release: supported
  • dev commands (test, format, lint, cov): supported
• Dart:
  • build: supported in library mode only
  • release: supported with release.includeArtifacts: false
  • dev commands: supported
  • test --style per_test: supported (uses Dart JSON reporter)
  • cov threshold enforcement: supported (reads .dart_tool/coverage/lcov.info)
• Python 3 with uv:
  • build: wheel and source distribution in package mode, with checksums and optional tests
  • release: GitHub releases with or without package artifacts
  • test, format, lint, cov: supported, including per-test output and coverage thresholds
• Rust with Cargo:
  • build: library verification, target binaries, and verified .crate packages
  • release: GitHub releases with fresh build artifacts or without assets
  • test, format, lint, cov: supported, including workspace tests, per-test output, and line coverage thresholds

Notes

• Topics are managed as a flat list of strings.
• Labels are managed as structured objects with name, color, and description.
• Build: Go supports binary and library; Dart supports library; Python supports package; Rust supports all three.
• Release: Dart currently supports release.includeArtifacts: false.
• build.mode defaults to binary. Use library for Go/Dart/Rust verification or package for Python/Rust distributions. build.runTests enables optional tests during builds.
• build.mainPackage controls the Go main package (default ./cmd/<project.repo>) or Rust manifest directory (default .) used for binary builds.
• build.artifactTargetSuffix controls whether artifact names include -os-arch suffixes.
  • when false with multiple targets, artifacts are written under per-target subdirectories to avoid filename collisions.
• In library mode, --target applies GOOS/GOARCH cross-compile checks and does not force artifact generation.
• go.cgo uses camelCase keys only: enabled, cc, cxx.
• go.cacheDir and go.modCacheDir should be project-relative (for example ./.gocache); gh flarebyte resolves them to absolute paths at runtime before invoking Go.
• Absolute go.cacheDir and go.modCacheDir values still work, but emit portability warnings.
• When go.cgo.enabled: true, gh flarebyte build sets CGO_ENABLED=1 (and applies CC/CXX when configured).
• When go.cgo.enabled: false, the build keeps CGO_ENABLED=0 and fails with a policy error if CGO-backed dependencies are detected.
• release.includeArtifacts defaults to true. Set it to false to publish tag and notes without uploading binaries or checksums.
• gh flarebyte cov --min 90 overrides config coverage threshold for that invocation.
• For Dart projects, cov computes total line coverage from .dart_tool/coverage/lcov.info and enforces coverage.min / --min when coverage.enforceMin is enabled.
• If .dart_tool/coverage/lcov.info is missing after dart test --coverage, cov attempts to generate it via coverage:format_coverage.
• devOutput.style supports summary and per_test.
• --color overrides devOutput.color for test, lint, and cov.
• --failed-only suppresses PASS summary output for test, lint, and cov.
• In per_test style, test prints ✓/↷/✗ per test (Go, Dart, Python, and Rust) and cov prints ✓/✗ per coverage entry; with --failed-only, only failing entries are shown.