# dive: Fail the Build on Image Efficiency

> dive in CI mode enforces efficiency and wasted-space thresholds. Reference for CI=true, the rule env vars, .dive-ci, and the failure errors.

Source: https://latchkey.dev/learn/command-reference/dive-ci-rules  
Updated: 2026-06-30

dive with CI=true checks an image against efficiency and wasted-space rules, failing the build when it is too bloated.

Beyond inspection, dive can gate. Set thresholds for the minimum efficiency and the maximum wasted space, and dive exits non-zero when an image violates them.

## What it does

When CI=true, dive runs headless and evaluates three rules: a minimum efficiency score (lowestEfficiency), a maximum wasted-bytes budget (highestWastedBytes), and a maximum wasted-percent (highestUserWastedPercent). Any rule that fails makes dive exit non-zero. Rules come from env vars or a .dive-ci config file.

## Common usage

```Terminal
CI=true dive myorg/app:ci
# tighten the thresholds via env vars
CI=true \
  DIVE_LOWESTEFFICIENCY=0.95 \
  DIVE_HIGHESTWASTEDBYTES=20MB \
  DIVE_HIGHESTUSERWASTEDPERCENT=0.10 \
  dive myorg/app:ci
# or via a .dive-ci file
dive myorg/app:ci --ci-config .dive-ci
```

## Options

| Rule / flag | What it does |
| --- | --- |
| lowestEfficiency | Minimum acceptable efficiency score (0-1) |
| highestWastedBytes | Maximum wasted bytes allowed (e.g. 20MB) |
| highestUserWastedPercent | Maximum fraction of wasted space (0-1) |
| --ci-config <file> | Path to a .dive-ci rules file |
| CI=true | Enable headless CI mode |

## In CI

Commit a .dive-ci with your thresholds so they are reviewed, and run CI=true dive on the built image. Start lenient and tighten lowestEfficiency over time; a disabled rule is set to -1. Combine with a Trivy scan in the same job to cover both bloat and vulnerabilities.

## Common errors in CI

The job fails with "Result:FAIL [Total:3] [Passed:2] [Failed:1]" naming the violated rule; loosen that threshold or slim the image. A rule that never trips is likely set to -1 (disabled) in .dive-ci. The same no-daemon error as plain dive applies; supply a docker-archive:// or podman:// source.

## FAQ

### dive: Fail the Build on Image Efficiency?

Beyond inspection, dive can gate. Set thresholds for the minimum efficiency and the maximum wasted space, and dive exits non-zero when an image violates them.

### What it does?

When CI=true, dive runs headless and evaluates three rules: a minimum efficiency score (lowestEfficiency), a maximum wasted-bytes budget (highestWastedBytes), and a maximum wasted-percent (highestUserWastedPercent). Any rule that fails makes dive exit non-zero. Rules come from env vars or a .dive-ci config file.

### In CI?

Commit a .dive-ci with your thresholds so they are reviewed, and run CI=true dive on the built image. Start lenient and tighten lowestEfficiency over time; a disabled rule is set to -1. Combine with a Trivy scan in the same job to cover both bloat and vulnerabilities.

### Common errors in CI?

The job fails with "Result:FAIL [Total:3] [Passed:2] [Failed:1]" naming the violated rule; loosen that threshold or slim the image. A rule that never trips is likely set to -1 (disabled) in .dive-ci. The same no-daemon error as plain dive applies; supply a docker-archive:// or podman:// source.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt