gen-circleci-orb

Generate a CircleCI orb to provide the facilities offered by a CLI program.

Overview

gen-circleci-orb reads the --help output of any CLI binary and generates a complete CircleCI orb: one command and one job per subcommand, an executor, a Dockerfile, and optionally the CI configuration to keep the orb in sync with the binary automatically.

Installation

cargo binstall gen-circleci-orb
# or
cargo install gen-circleci-orb

Quick start

Step 1 — generate orb source for your binary (run from project root):

gen-circleci-orb generate \
  --binary my-tool \
  --orb-namespace my-org

This writes orb source into an orb/ subdirectory (the default --orb-dir):

• orb/src/@orb.yml — orb metadata (version, description)
• orb/src/commands/<subcommand>.yml — one per leaf subcommand
• orb/src/jobs/<subcommand>.yml — one per leaf subcommand
• orb/src/executors/default.yml — Docker executor with a tag parameter
• orb/Dockerfile — image that pre-installs your binary

The orb source is always isolated in its own subdirectory so it cannot be confused with existing project source. If the target directory already exists but doesn't contain a CircleCI orb, an error is raised.

Step 2 — wire orb generation into CI:

# Public orb in a single namespace
gen-circleci-orb init \
  --binary my-tool \
  --public-orb-namespace my-org \
  --docker-namespace my-docker-org \
  --build-workflow validation \
  --release-workflow release \
  --requires-job common-tests \
  --release-after-job release-my-tool

# Mixed: production namespace public, pre-production namespace private
gen-circleci-orb init \
  --binary my-tool \
  --public-orb-namespace my-org \
  --private-orb-namespace my-org-preprod \
  --docker-namespace my-docker-org \
  --build-workflow validation \
  --release-workflow release \
  --requires-job common-tests \
  --release-after-job release-my-tool

This patches .circleci/config.yml and .circleci/release.yml to add:

• A regenerate-orb job that re-runs generate on every build
• orb-tools/pack + orb-tools/review steps to verify the generated orb
• A build-container job in the release workflow to publish the Docker image
• An orb-tools/publish step to publish the orb to the CircleCI registry

generate reference

gen-circleci-orb generate [OPTIONS] --binary <BINARY> --orb-namespace <NAMESPACE>

Options:
  --binary <BINARY>               Binary to introspect (must be on PATH)
  --orb-namespace <NAMESPACE>     CircleCI orb namespace (repeatable)
  --output <DIR>                  Project root directory [default: .]
  --orb-dir <DIR>                 Orb subdirectory within --output [default: orb]
  --install-method <METHOD>       binstall | apt [default: binstall]
  --base-image <IMAGE>            Docker base image [default: debian:12-slim]
  --home-url <URL>                Home URL for orb registry display
  --source-url <URL>              Source URL for orb registry display
  --dry-run                       Print planned files, write nothing

init reference

gen-circleci-orb init [OPTIONS] --binary <BINARY>
                                 --public-orb-namespace <NS> | --private-orb-namespace <NS>
                                 --docker-namespace <NS>
                                 --build-workflow <WF> --release-workflow <WF>

Required:
  --binary <BINARY>                   Binary to introspect (must be on PATH)
  --public-orb-namespace <NS>         CircleCI orb namespace, registered public (repeatable)
  --private-orb-namespace <NS>        CircleCI orb namespace, registered private (repeatable)
  --docker-namespace <NS>             Docker Hub (or registry) namespace for the container image
  --build-workflow <WF>           Validation workflow name to patch
  --release-workflow <WF>         Release workflow name to patch

Options:
  --requires-job <JOB>            Job regenerate-orb should require
  --release-after-job <JOB>       Job build-container should require
  --orb-dir <DIR>                 Orb output directory [default: orb]
  --ci-dir <DIR>                  CircleCI config directory [default: .circleci]
  --orb-tools-version <VER>       circleci/orb-tools pin [default: 12.3.3]
  --docker-orb-version <VER>      circleci/docker pin [default: 3.2.0]
  --docker-context <CTX>          CircleCI context for Docker Hub credentials [default: docker-credentials]
  --orb-context <CTX>             CircleCI context for orb publish credentials [default: orb-publishing]
  --mcp                           Wire in toolkit/build_mcp_server (jerus-org toolkit only)
  --dry-run                       Print planned changes, write nothing

Generated artifacts

Parameter required vs optional

A parameter is required in the generated orb only if the CLI itself requires it — read from the Usage: line: flags outside any [...] group are required; flags inside [OPTIONS] are optional.

Optional parameters always have a default: so orb consumers can omit them:

• boolean flags default to false
• string/enum flags with a CLI default use that value
• string flags with no CLI default use "" (empty string)

The run step uses CircleCI mustache conditionals for optional parameters so blank or false values are not forwarded as empty flags to the binary.

Excluded flags

Two flags are always excluded from the generated output:

• -h/--help — clap built-in
• -V/--version with no <VALUE> metavar — clap built-in (prints binary version)

An application flag named --version that accepts a value (e.g. --version <VERSION>) is not excluded. However, reusing the -V/--version name for application purposes is discouraged: it conflicts with the widely-understood convention and requires special-case handling in any tool that parses --help output. Prefer an explicit name such as --crate-version or --output-version instead.

Environment requirements

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Contributing

See the Contributing Guide and Code of Conduct.

Changelog

See CHANGELOG.md for release history.