> ## Documentation Index
> Fetch the complete documentation index at: https://keel-cloud.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Every keel command and flag: init, validate, dev, deploy, manifest, skills, and update, plus the background update check and where the CLI keeps its state.

```console theme={null}
$ keel --help
$ keel --version
$ keel <command> --help
```

All commands work relative to the current directory unless a directory
argument is given.

## `keel init`

```console theme={null}
$ keel init [dir]
```

Creates a starter `keel.yaml` (one sample deployment named `production`) and
`deploy/Dockerfile` (Alpine with `bash`, `curl`, `git`) in `dir` (default
`.`). Existing files are never overwritten; the command says which files it
created or kept.

## `keel validate`

```console theme={null}
$ keel validate [dir]
```

Parses and validates the configuration in `dir`. On success prints each
deployment with its step and variable counts and exits 0. On failure lists
every problem with its path and exits 1. The rules are on the
[validation page](https://keel-cloud.mintlify.site/reference/validation.md#configuration-rules).

## `keel dev`

```console theme={null}
$ keel dev [dir] [-p PORT] [--host HOST]
```

Runs the local Keel UI for the repository in `dir`. If there is no
`keel.yaml`, the starter files are created first.

| Flag | Default | Description |
| - | - | - |
| `-p`, `--port` | `3400` | Port to listen on |
| `--host` | `127.0.0.1` | Address to bind. `0.0.0.0` exposes the UI on the network — there is no authentication in Keel Dev. |

On start, Keel checks that Docker is reachable and warns if not; the UI
works, but deploys fail until Docker is running. Ctrl+C shuts down
gracefully. State goes to `.keel/` in the repository (see below).

## `keel deploy`

```console theme={null}
$ keel deploy <deployment> [-t TARGET] [--var NAME=value]... [--var-file FILE]
```

Runs a deployment headlessly: builds the environment image, executes the
steps, streams the log to the terminal, prints outputs on success. Requires
Docker.

| Flag | Description |
| - | - |
| `-t`, `--target` | Use the saved values of this target from `.keel/dev.db`. The target must have been created in `keel dev` on this machine. |
| `--var` | Set one variable, `NAME=value`. Repeatable. Highest precedence. |
| `--var-file` | An env-style file, `NAME=value` per line with `#` comments. |

Precedence, lowest to highest: defaults, target values, var file, `--var`.
Values for undeclared variables are ignored. Missing or invalid values are
listed and the command exits 1 before anything runs; the same happens if
Docker is unreachable or the configuration is invalid. Ctrl+C cancels the
run. Exit status is 0 only when every step succeeded.

Without `--target`, `KEEL_TARGET` inside the run is `cli`.

## `keel manifest`

```console theme={null}
$ keel manifest <deployment> [-o FILE] [-f md|html] [--var NAME]... [--project NAME]
```

Generates the variable manifest. See the
[manifest reference](https://keel-cloud.mintlify.site/reference/manifest.md#cli) for the flags.

## `keel skills`

```console theme={null}
$ keel skills install [dir] [-a AGENT]... [-g] [--to DIR] [--skill NAME]... [--force]
$ keel skills uninstall [dir] [-a AGENT]... [-g] [--to DIR] [--skill NAME]...
$ keel skills list
$ keel skills agents
```

Installs the Keel agent skills — `SKILL.md` documents that teach AI coding
agents how to write `keel.yaml`, environment images, and use the CLI —
into the agents' skill directories. See
[Use Keel with AI coding agents](https://keel-cloud.mintlify.site/guides/ai-agents.md).

| Flag | Default | Description |
| - | - | - |
| `-a`, `--agent` | the agents detected on this machine | Agent key to target; repeatable. `all` targets every supported agent. With no agent detected, the shared `.agents/skills` directory is used. |
| `-g`, `--global` | off | Write to the agents' user-wide directories instead of `dir` (default `.`). |
| `--to` | — | Write to this directory instead of any agent's. Not combinable with `--agent` or `--global`. |
| `--skill` | all | Skill to include; repeatable. |
| `--force` | off | `install` only: replace a same-named skill directory that Keel did not write. |

`install` replaces skill directories Keel wrote (re-run it after
upgrading), never touches other directories without `--force`, and prints
each directory with the agents that read it. `uninstall` removes only
directories Keel wrote. `list` prints the shipped skills with their
descriptions and files. `agents` prints every supported agent with its
key, project and user-wide directories, and whether it was detected.

## `keel update`

```console theme={null}
$ keel update [--check] [--version TAG] [--force]
```

Downloads the latest release from GitHub, verifies the archive's SHA-256
against the release's `checksums.txt`, and replaces the running executable
in place — the same procedure as the install script, without re-running it.
Afterwards it runs the new binary's `--version` to confirm it works.

| Flag | Description |
| - | - |
| `--check` | Report whether a newer release exists and exit without installing. |
| `--version` | Install this release tag instead of the latest, for example `v0.3.0`. Allows downgrades. |
| `--force` | Replace a development build (one whose version is not a release tag, such as `dev` or a commit hash) with a release. Without it, `keel update` refuses on such builds. |

When the executable's directory is not writable, the command says so —
re-run it with elevated permissions (`sudo keel update`) or use the install
script. On Windows the old executable is renamed to `keel.exe.old` next to
the new one, because a running program cannot be overwritten; delete it at
any time.

### Background update check

Every command checks for a newer release **at most once a day**. The
request runs while the command does; a command that finishes first waits
at most two seconds for the answer, and on every other day the saved
answer is used with no request at all. When a newer release is known, a
note is printed on standard error after the command finishes:

```text theme={null}
A new release of keel is available: v0.3.0 → v0.4.0
Run `keel update` to install it.
```

The check contacts `https://github.com/UcGeorge/keel/releases/latest` and
sends nothing but the request. It is skipped for development builds, when
`KEEL_NO_UPDATE_CHECK` is set to any value, or when `CI` is set. The last
answer is kept in `update-check.json` under the user config directory
(next to `dev.key`, see below).

## State on disk

| Path | Contents |
| - | - |
| `<repo>/.keel/dev.db` | SQLite: targets, encrypted values, runs, logs, outputs. Created by `keel dev`. |
| `<repo>/.keel/.gitignore` | Written by Keel so the database stays out of git while `.keel/bin` (from embedding) can be committed. |
| `update-check.json` under the user config directory | When the background update check last ran and the newest release it found. Safe to delete. |
| `dev.key` under the user config directory | The AES-256 key for every `.keel/dev.db` on this machine. macOS `~/Library/Application Support/keel/dev.key`; Linux `$XDG_CONFIG_HOME/keel/dev.key` (usually `~/.config/keel/dev.key`); Windows `%AppData%\keel\dev.key`. Created on first use. |

Deleting `dev.key` makes every saved value on the machine unreadable; copy
it to move a `.keel/dev.db` to another machine.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | Any error: invalid configuration, value problems, Docker unreachable, a failed or canceled run. The message on standard error says which. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.