Command-line interface

Available BuildCharts commands and how to use them.

The buildcharts CLI scaffolds projects, manages chart dependencies, validates configuration, and generates build artifacts from build.yml metadata.

Commands

Command	What it does
clean	WIP
diff	WIP
explain	WIP
generate	Generates .buildcharts/docker-bake.hcl from metadata/charts
init	Scaffolds build.yml and charts/buildcharts/Chart.yaml
package	WIP
pull	Pulls a single OCI chart by tag or digest
summary	Creates a summary from latest Docker Buildx history
update	Refreshes charts/buildcharts/Chart.lock from Chart.yaml
validate	WIP
version	Prints tool and runtime version info

buildcharts generate

Generates build pipeline using metadata. Outputs a Docker bake file .buildcharts/docker-bake.hcl. It also validates Chart.yaml digests by comparing them to chart tags, runs plugins, and cleans the .buildcharts folder to keep a clean state.

buildcharts generate [--use-inline-dockerfiles] [--ignore-lock] [--verbose]

--use-inline-dockerfiles · option

Embed pulled Dockerfiles directly in .buildcharts/docker-bake.hcl

--ignore-lock · option

Skip Chart.lock validation even if the file exists

--verbose · option

Enable extra plugin and generator logging by setting BUILDSCHARTS_VERBOSE=1

DOCKER_CONFIG · environment

Override the Docker config directory used for registry auth

Example

# buildcharts generate
Pulling charts...
Pulled: registry-1.docker.io/buildcharts/dotnet-test:0.0.1 (581 bytes)
Digest: sha256:e2fc7641da11faa2f90d2a4991fa8c37e97a0825988f1d4352758da4bc5dd587
Pulled: registry-1.docker.io/buildcharts/dotnet-docker:0.0.2 (583 bytes)
Digest: sha256:d3a3957520bff850383d6d79b692888595f437c872c2f860d75544751813ddde
Pulled: registry-1.docker.io/buildcharts/dotnet-build:0.0.1 (582 bytes)
Digest: sha256:aca33142a81a9e79d584de7882a740240163e27411ad0f4ebe0336ed2de0cb4e
Pulled: registry-1.docker.io/buildcharts/dotnet-nuget:0.0.1 (582 bytes)
Digest: sha256:6b6b99dd94c8b9f388890770fc3f1249c07561c9347d9eb98802c3bf44fbf47a

✅ Generated files:
  • docker-bake.hcl

buildcharts init

buildcharts init

Scaffolds the working directory and automatically creates:

• build.yml
• charts/buildcharts/Chart.yaml

Currently only supports .NET applications.

Example

# buildcharts init
buildcharts initialized

✅ Generated files:
  • build.yml
  • charts/buildcharts/Chart.yaml

✅ Targets:
  • buildcharts.sln → build
  • src/BuildCharts.Tool/BuildCharts.Tool.csproj → nuget

✅ Detected GitHub from .git folder:
  • .github/workflows/buildcharts.yml

👉 Next steps:
  • Edit `build.yml` to customize build pipeline
  • Run `buildcharts generate` to generate build pipeline
  • Run `docker buildx bake` to run build pipeline

💡 Tips:
  • Run `buildcharts update` to auto-sync chart dependencies
  • Customize default base images and tags in `charts/buildcharts/Chart.yaml`

buildcharts pull

buildcharts pull <reference> [--untar] [--untardir <DIR>] [--output <OUTPUT>]

Pulls a single OCI chart by tag or digest.

reference · argument · required

OCI reference in the form registry/repo:tag or registry/repo@sha256:...

--untar · option

Extract the downloaded chart into the current directory

--untardir <DIR> · option

Extraction directory when --untar is set

--output <OUTPUT> · option

Directory where the downloaded chart blob is stored

DOCKER_CONFIG · environment

Override the Docker config directory used for registry auth

Example

# buildcharts pull oci://docker.io/buildcharts/dotnet-build:0.0.1                    
Pulled: docker.io/buildcharts/dotnet-build:0.0.1 (1123 bytes)
Digest: sha256:4da50de6250055a119d51c620e2ed825529d281b2d27a9e2bb1f17b912d1a11c

# buildcharts pull oci://registry-1.docker.io/buildcharts/dotnet-build@sha256:4da50de6250055a119d51c620e2ed825529d281b2d27a9e2bb1f17b912d1a11c
Pulled: registry-1.docker.io/buildcharts/dotnet-build@sha256:4da50de6250055a119d51c620e2ed825529d281b2d27a9e2bb1f17b912d1a11c (1123 bytes)
Digest: sha256:4da50de6250055a119d51c620e2ed825529d281b2d27a9e2bb1f17b912d1a11c

buildcharts summary

buildcharts summary

Exports summary artifacts from the latest Docker Buildx history.

GITHUB_STEP_SUMMARY · environment

When set, summary appends the generated Markdown summary to this file (GitHub Actions).

TF_BUILD=true · environment

When set, summary also writes Azure DevOps-oriented outputs (artifacts and job summary metadata).

Example

# buildcharts summary
Generating summary for build: <id> (<job>)

✅ Generated files:
  • .buildcharts/output/SUMMARY.md
  • .buildcharts/output/buildcharts.dockerbuild

buildcharts update

buildcharts update

Resolves chart dependency digests from charts/buildcharts/Chart.yaml and refreshes the lock file.

DOCKER_CONFIG · environment

Override the Docker config directory used for registry auth

Example

# buildcharts update
Updating 4 dependencies...
Pulled: registry-1.docker.io/buildcharts/dotnet-build:0.0.1 (1111 bytes) (cached)
Digest: sha256:ca7e6c16d053721518ebf6186c5c0663ed870c14c2eda6b0f62588b49b2a1ab6 (cached)
Pulled: registry-1.docker.io/buildcharts/dotnet-test:0.0.1 (900 bytes) (cached)
Digest: sha256:ab2b1d00fbc03f0300d2b10a78ed60ee8615e6bcafc60222083e77ce572583a9 (cached)
Pulled: registry-1.docker.io/buildcharts/dotnet-nuget:0.0.1 (1853 bytes) (cached)
Digest: sha256:bab5a1e71c486731e152c55e2aa54eb045921f865441ac948ef8a572346ae21e (cached)
Pulled: registry-1.docker.io/buildcharts/dotnet-docker:0.0.2 (752 bytes) (cached)
Digest: sha256:978e3277b9618f6a0a56978b96d0b3fd23246cd77b972b66820c53e145c42de4 (cached)

✅ Generated files:
  • charts/buildcharts/Chart.lock

buildcharts version

buildcharts version

Prints tool and runtime version details.

Example

# buildcharts version
buildcharts
 version:       1.0.0+a882a7c19eb72f60a9cf1da3a4aee00691bdc4ba
 built:         2026-01-09T01:55:30Z
 os/arch:       Microsoft Windows 10.0.26200/x64
 cpu/mem:       32 cores/127.65 GB
 .NET version:  10.0.1