> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line interface

> Available BuildCharts CLI commands and how to use them.

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

## Commands

| Command    | What it does                                                  |
| ---------- | ------------------------------------------------------------- |
| `clean`    | <Badge color="purple" size="sm">WIP</Badge>                   |
| `diff`     | <Badge color="purple" size="sm">WIP</Badge>                   |
| `explain`  | <Badge color="purple" size="sm">WIP</Badge>                   |
| `generate` | Generates `.buildcharts/docker-bake.hcl` from metadata/charts |
| `init`     | Scaffolds `build.yml` and `charts/buildcharts/Chart.yaml`     |
| `package`  | <Badge color="purple" size="sm">WIP</Badge>                   |
| `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` | <Badge color="purple" size="sm">WIP</Badge>                   |
| `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.

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts generate [--use-inline-dockerfiles] [--ignore-lock] [--verbose]
```

<ResponseField name="--use-inline-dockerfiles" type="option">
  Embed pulled Dockerfiles directly in `.buildcharts/docker-bake.hcl`
</ResponseField>

<ResponseField name="--ignore-lock" type="option">
  Skip `Chart.lock` validation even if the file exists
</ResponseField>

<ResponseField name="--verbose" type="option">
  Enable extra plugin and generator logging by setting `BUILDSCHARTS_VERBOSE=1`
</ResponseField>

<ResponseField name="DOCKER_CONFIG" type="environment">
  Override the Docker config directory used for registry auth
</ResponseField>

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# 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:
  • .buildcharts/docker-bake.hcl
```

## `buildcharts init`

Scaffolds the working directory and automatically creates:

* `build.yml`
* `charts/buildcharts/Chart.yaml`

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts init
```

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# 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`

Pulls a single OCI chart by tag or digest.

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts pull <reference> [--untar] [--untardir <DIR>] [--output <OUTPUT>]
```

<ResponseField name="reference" type="argument" required>
  OCI reference in the form `registry/repo:tag` or `registry/repo@sha256:...`
</ResponseField>

<ResponseField name="--untar" type="option">
  Extract the downloaded chart into the current directory
</ResponseField>

<ResponseField name="--untardir <DIR>" type="option">
  Extraction directory when `--untar` is set
</ResponseField>

<ResponseField name="--output <OUTPUT>" type="option">
  Directory where the downloaded chart blob is stored
</ResponseField>

<ResponseField name="DOCKER_CONFIG" type="environment">
  Override the Docker config directory used for registry auth
</ResponseField>

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# 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`

Exports summary artifacts from the latest Docker Buildx history.

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts summary
```

<ResponseField name="GITHUB_STEP_SUMMARY" type="environment">
  When set, `summary` appends the generated Markdown summary to this file (GitHub Actions).
</ResponseField>

<ResponseField name="TF_BUILD=true" type="environment">
  When set, `summary` also writes Azure DevOps-oriented outputs (artifacts and job summary metadata).
</ResponseField>

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# buildcharts summary
Generating summary for build: <id> (<job>)

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

## `buildcharts update`

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

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts update
```

<ResponseField name="DOCKER_CONFIG" type="environment">
  Override the Docker config directory used for registry auth
</ResponseField>

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# 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`

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts version
buildcharts --version
```

`buildcharts version` prints tool and runtime version details.
`buildcharts --version` prints the short root-command version output.

**Example**

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# buildcharts --version
buildcharts v1.0.0, build a882a7c19eb72f60a9cf1da3a4aee00691bdc4ba

# 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
```