> For the complete documentation index, see [llms.txt](https://blbl.gitbook.io/blcli-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://blbl.gitbook.io/blcli-docs/readme.md).

# blcli Documentation

Official documentation for blcli and blcli template repositories.

`blcli` is an open-source Infrastructure-as-Code CLI for GCP, Kubernetes, and GitOps workflows. It turns one `args.yaml` plus a self-describing template repository into generated Terraform, Kubernetes manifests, GitOps files, and staged operations.

This documentation covers the public project repositories:

* [`ggsrc/blcli`](https://github.com/ggsrc/blcli): the CLI that renders, checks, applies, inspects, rolls back, and destroys infrastructure.
* [`ggsrc/bl-template`](https://github.com/ggsrc/bl-template): the enterprise/team-scale template for multi-project GCP platforms, Kubernetes add-ons, and ArgoCD GitOps.
* [`ggsrc/bl-template-personal`](https://github.com/ggsrc/bl-template-personal): the solo-developer template for one GCP project and one GKE cluster. Its default `minimal` profile does not install ArgoCD; deploy apps with `kubectl` or Helm unless you opt into GitOps.

The project is GCP-first today. It does not replace Terraform, `kubectl`, Helm, ArgoCD, `gcloud`, or `gh`; it gives them a repeatable template-driven workflow.

```
args.yaml + template repository -> blcli -> terraform/ + kubernetes/ + gitops/
```

## Who Should Use It

| User                                      | Start with                   | Typical goal                                                              |
| ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| Platform and SRE teams                    | `ggsrc/bl-template`          | Multi-project GCP org with `corp`, `stg`, `prd`, GKE, ArgoCD, and GitOps. |
| Solo developers and AI-assisted workflows | `ggsrc/bl-template-personal` | Single low-burden project and cluster with `minimal` or `full` profile.   |
| Template authors                          | either template              | Fork the contract and replace components, defaults, and dependencies.     |

## Start Here

* [Overview](/blcli-docs/overview.md)
* [Install](/blcli-docs/install.md)
* [Quickstart](/blcli-docs/quickstart.md)
* [Workflow](/blcli-docs/workflow.md)
* [Use Cases](/blcli-docs/use-cases.md)
* [Operations Commands](/blcli-docs/commands/operations.md)
* [Agent Workflows](/blcli-docs/commands/agent-workflows.md)
* [Troubleshooting](/blcli-docs/reference/troubleshooting.md)

## Documentation Model

The docs are organized around the normal operator journey:

1. Understand the `blcli` and `bl-template` model.
2. Install the CLI and the external tools it orchestrates.
3. Generate `args.yaml` from the template repository.
4. Edit project, cluster, component, and GitOps values.
5. Render a workspace with `terraform/`, `kubernetes/`, and `gitops/`.
6. Apply generated output in explicit stages.
7. Use [Operations Commands](/blcli-docs/commands/operations.md) for status, rollback, and cleanup.
8. Use [Agent Workflows](/blcli-docs/commands/agent-workflows.md) for `contract`, `diagnose`, and `runs`.
9. Use [Troubleshooting](/blcli-docs/reference/troubleshooting.md) to isolate failures by layer.

English is the default documentation language. Chinese is published as a separate GitBook variant so readers can switch languages from the top language selector.