---
title: "Run locally"
description: "Check a build file, see what a push would run, and run your working tree without a push, with ezgh build."
---

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

# Run locally

`ezgh build` works from a checkout of the repository. `<connection>` is a connection's ID or name;
with one connection in the project it needn't be given. `--json` prints JSON.

## Validate

```sh
ezgh build validate
```

Checks `.ezgh/build.yaml`, or the file named. Every problem is printed with its place in the file,
the reason and an example that would be accepted; the exit code is 1 when there is one. The format
is checked without a request. When you are logged in, the bots, secrets, buckets, clusters and
images the file names are then looked up with your own credential.

## Plan

```sh
ezgh build plan
ezgh build plan --commit 4f2a9c1 --ref refs/heads/main
```

Says what a run would do, task by task: `run`, `cached` or `skipped`, and for a task that would run,
why (`no earlier run`, `definition changed`, `inputs changed` or `<task> changed`). The plan is
computed from your checkout: the working tree as it is, or a commit with `--commit` and `--ref`.
Only each task's key is sent; no file leaves your machine.

## Run

```sh
ezgh build run
ezgh build run --no-cache
```

Runs the build file of your checkout as it is on disk, uncommitted changes included, and follows it.
The exit code is 1 unless the pipeline succeeds. Ctrl-C stops following and cancels nothing.

- The files Git would commit (tracked and untracked, not ignored) are uploaded to the project's
  registry.
- The run is on `refs/local/<branch>`. It reads what trusted runs have cached and writes only its
  own results.
- It needs `build.pipelines.run` on the connection and permission to push to the project's
  registry.
- A task's bot must [trust](/build/bots-and-trust) EZGH Build on `refs/local/<branch>`. A bot that
  trusts only `refs/heads/main` refuses, and the task fails.
- A `build` task's image is tagged `local-<pipeline ID>` only.

## Follow, read and rerun

| Command | Does |
| --- | --- |
| `ezgh build wait [pipeline]` | Follows a pipeline to its end: each task's log, then the outcome |
| `ezgh build logs [pipeline] --failed` | Each failed task's name, exit code and the last 40 lines of its log |
| `ezgh build rerun [pipeline]` | Starts a new pipeline for the same commit. `--no-cache` runs every task; `--follow` follows it |
| `ezgh build pipelines list` | The connection's pipelines, newest first |
| `ezgh build pipelines get <pipeline>` | A pipeline and its tasks |

Without a pipeline, `wait`, `logs` and `rerun` use the connection's newest pipeline of your checkout's `HEAD` commit.

Source: https://docs.ezghcloud.com/build/run-locally/index.mdx
