# CLI commands

> Every patchula command, argument and flag, generated from the CLI's usage spec.

Count Patchula vants to update your deps. A modern dependency updater with strong defaults.

Exit codes: 0 = success; 1 = runtime error; 2 = usage or configuration error; `lookup`, `tui --once` and `apply` add 4 = a lookup failed; `apply` adds 3 = updates still waiting; `run` adds 5 = a repository changed during the run; run again.

## Examples

Report updates for the checkout here

```sh
patchula lookup
```

Plan branches and diffs, writing nothing

```sh
patchula run --dry-run
```

Browse updates and apply the ones you pick

```sh
patchula tui
```

Exit 3 in CI while updates are waiting

```sh
patchula apply --check
```

Write only GitHub Actions updates

```sh
patchula apply --manager github-actions
```

Run the GitHub App webhook server

```sh
patchula serve --settings settings.pkl
```

- **Usage:** `patchula [FLAGS] [SUBCOMMAND]`

## Global Flags

| Flag | Description | Default |
| - | - | - |
| `--recheck <WHEN>` | When a ticked checkbox says it takes effect; also PATCHULA_RECHECK. Default: now in the server, next-run in the CLI. One of `now`, `next-run`. | |
| `-v --verbose` | Show request counts and phase timings after a batch; repeat for debug logs. | |
| `--color <WHEN>` | Control ANSI colors in diagnostics. One of `auto`, `always`, `never`. | `auto` |
| `--json` | Emit command results and errors as JSON; configs stay Pkl. | |

## Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |
| `-V --version` | Print version | |

## `patchula apply`

- **Usage:** `patchula apply [FLAGS]`

Write available updates into the working tree here, without branches or pull requests.

Exit codes: 0 = nothing selected is left to apply; 1 = runtime error; 2 = usage or configuration error; 3 = selected updates are still waiting: `--check` or `--dry-run` found some, or some could not be written in place; 4 = a dependency’s lookup failed, so its updates are unknown. 4 takes precedence over 3.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--cache <DIR>` | Cache directory, shared by every checkout. Default: `patchula` in the user cache directory (`~/Library/Caches` on macOS, else `XDG_CACHE_HOME` or `~/.cache`). | |
| `--settings <FILE>` | Operator settings file; also PATCHULA_SETTINGS. Default: `patchula/settings.pkl` in the user config directory (`XDG_CONFIG_HOME` or `~/.config`), when it exists. Keeps the run on this machine; a server uses its own settings. | |
| `--concurrency <N>` | Maximum concurrent repository scans (1–100), overriding the settings file; HTTP limits are per host. Default: 8. | |
| `--config <FILE>` | Local Pkl override applied to every selected repository. | |
| `--default-config` | Use the Count’s defaults when the working tree has no `patchula.pkl`, instead of asking. Conflicts with `--config` and `--config-dir`. | |
| `--manager <MANAGER>` | Only updates from this manager, such as github-actions; repeat for more. | |
| `--dependency <PATTERN>` | Only dependencies matching this name or package, with config’s `glob:`, `regex:` and `!`; repeat for more. | |
| `--type <TYPE>` | Only updates of this type; repeat for more. One of `major`, `minor`, `patch`, `pin`, `digest`. | |
| `--dry-run` | Print the unified diff of what would be written, and write nothing. | |
| `--check` | Write nothing; exit 3 if any selected update is waiting, or 4 if a lookup failed. | |
| `--copier` | Also run your own `copier update` for each selected template, before the other updates. The template’s code runs on this machine as you. The tree must be clean, the Count never passes `--trust`, and copier asks its questions on the terminal. | |
| `--copier-defaults` | With `--copier`, take the defaults for questions copier would ask, for use without a terminal. | |
| `-h --help` | Print help | |

### Examples

Write every available update here

```sh
patchula apply
```

Write nothing; exit 3 if updates are waiting

```sh
patchula apply --check
```

Show the patch updates as a diff

```sh
patchula apply --dry-run --type patch
```

Write only the actions/\* updates

```sh
patchula apply --manager github-actions --dependency 'glob:actions/*'
```

## `patchula auth`

- **Usage:** `patchula auth <SUBCOMMAND>`

Sign in to or out of a Count Patchula server for `--remote`.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

### Examples

Sign in through the server’s GitHub App

```sh
patchula auth login --server https://patchula.example.com
```

Forget the token for PATCHULA_SERVER

```sh
patchula auth logout
```

## `patchula auth login`

- **Usage:** `patchula auth login [--server <URL>]`

Sign in with the server’s GitHub App, replacing any stored token.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--server <URL>` | Server URL; also PATCHULA_SERVER. | |
| `-h --help` | Print help | |

## `patchula auth logout`

- **Usage:** `patchula auth logout [--server <URL>]`

Forget the stored token for a server.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--server <URL>` | Server URL; also PATCHULA_SERVER. | |
| `-h --help` | Print help | |

## `patchula cache`

- **Usage:** `patchula cache <SUBCOMMAND>`

Inspect the cache directory’s database.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

### Examples

Print the cache schema this binary supports

```sh
patchula cache schema
```

## `patchula cache schema`

- **Usage:** `patchula cache schema`

Print the cache database schema this binary supports; it refuses a cache from a newer one.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

## `patchula config`

- **Usage:** `patchula config <SUBCOMMAND>`

Inspect and validate Pkl configuration.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

### Examples

Find and check this repository’s config

```sh
patchula config check .
```

Check one config file

```sh
patchula config check patchula.pkl
```

Save the schema for your editor

```sh
patchula config schema > PatchulaConfig.pkl
```

Check operator settings

```sh
patchula config check-settings settings.pkl
```

## `patchula config check`

- **Usage:** `patchula config check <PATH>`

Validate a Pkl config file or discover one in a repository directory.

### Arguments

| Argument | Description | Default |
| - | - | - |
| `<PATH>` | Pkl file or repository directory to check. | |

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

## `patchula config schema`

- **Usage:** `patchula config schema`

Print the bundled PatchulaConfig.pkl schema as Pkl source.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

## `patchula config settings-schema`

- **Usage:** `patchula config settings-schema`

Print the bundled PatchulaSettings.pkl operator schema.

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

## `patchula config check-settings`

- **Usage:** `patchula config check-settings <PATH>`

Validate an operator settings file without credentials or network.

### Arguments

| Argument | Description | Default |
| - | - | - |
| `<PATH>` | Settings file to check. | |

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

## `patchula lookup`

- **Usage:** `patchula lookup [FLAGS] [OWNER/REPO]…`

Report available updates without writing; with no repository, reads the working tree here.

### Arguments

| Argument | Description | Default |
| - | - | - |
| `[OWNER/REPO]…` | Repositories as owner/repo, read through the GitHub API; omit for the checkout here. | |

### Flags

| Flag | Description | Default |
| - | - | - |
| `--all-repos` | Process every repository the token can reach instead of naming them. | |
| `--cache <DIR>` | Cache directory, shared by every checkout. Default: `patchula` in the user cache directory (`~/Library/Caches` on macOS, else `XDG_CACHE_HOME` or `~/.cache`). | |
| `--settings <FILE>` | Operator settings file; also PATCHULA_SETTINGS. Default: `patchula/settings.pkl` in the user config directory (`XDG_CONFIG_HOME` or `~/.config`), when it exists. Keeps the run on this machine; a server uses its own settings. | |
| `--concurrency <N>` | Maximum concurrent repository scans (1–100), overriding the settings file; HTTP limits are per host. Default: 8. | |
| `--config <FILE>` | Local Pkl override applied to every selected repository. | |
| `--default-config` | Use the Count’s defaults when the working tree has no `patchula.pkl`, instead of asking. Conflicts with `--config` and `--config-dir`. | |
| `--config-dir <DIR>` | Per-repository overrides: `DIR/<owner>/<name>.pkl`, then `DIR/<name>.pkl`; other repositories use their own `patchula.pkl`, or are skipped without one. Conflicts with `--config`. | |
| `--remote` | Run on a Count Patchula server (PATCHULA_SERVER, or the one found for this checkout) with its credentials and caches; local config, cache and HTTP flags don’t apply. | |
| `--here` | Run on this machine, even if you chose to run this checkout on a server. | |
| `-h --help` | Print help | |

### Examples

Report updates for the checkout here

```sh
patchula lookup
```

Read two repositories through the API

```sh
patchula lookup acme/app acme/api
```

The same report, as JSON

```sh
patchula lookup --json
```

Look up on your Count Patchula server

```sh
patchula lookup --remote
```

## `patchula run`

- **Usage:** `patchula run [FLAGS] [OWNER/REPO]…`

Create or update dependency branches and pull requests with verified API commits.

With no repository, `--dry-run` plans from the working tree, uncommitted changes included. A real run with no repository opens pull requests for this checkout’s GitHub repository and requires a clean tree at the remote’s default branch.

Failed lookups are reported but the run still exits 0, since it keeps the pull requests it could plan; it holds off auto-merge and closing pull requests for that repository.

### Arguments

| Argument | Description | Default |
| - | - | - |
| `[OWNER/REPO]…` | Repositories as owner/repo, read through the GitHub API; omit for the checkout here. | |

### Flags

| Flag | Description | Default |
| - | - | - |
| `--all-repos` | Process every repository the token can reach instead of naming them. | |
| `--cache <DIR>` | Cache directory, shared by every checkout. Default: `patchula` in the user cache directory (`~/Library/Caches` on macOS, else `XDG_CACHE_HOME` or `~/.cache`). | |
| `--settings <FILE>` | Operator settings file; also PATCHULA_SETTINGS. Default: `patchula/settings.pkl` in the user config directory (`XDG_CONFIG_HOME` or `~/.config`), when it exists. Keeps the run on this machine; a server uses its own settings. | |
| `--concurrency <N>` | Maximum concurrent repository scans (1–100), overriding the settings file; HTTP limits are per host. Default: 8. | |
| `--config <FILE>` | Local Pkl override applied to every selected repository. | |
| `--default-config` | Use the Count’s defaults when the working tree has no `patchula.pkl`, instead of asking. Conflicts with `--config` and `--config-dir`. | |
| `--config-dir <DIR>` | Per-repository overrides: `DIR/<owner>/<name>.pkl`, then `DIR/<name>.pkl`; other repositories use their own `patchula.pkl`, or are skipped without one. Conflicts with `--config`. | |
| `--remote` | Run on a Count Patchula server (PATCHULA_SERVER, or the one found for this checkout) with its credentials and caches; local config, cache and HTTP flags don’t apply. | |
| `--here` | Run on this machine, even if you chose to run this checkout on a server. | |
| `--dry-run` | Print planned branches, files and unified diffs without writing to GitHub. | |
| `--allow-lockfile-pending` | For testing: write manifest-only branches for binary `bun.lockb` lockfiles, which can’t be regenerated. | |
| `-h --help` | Print help | |

### Examples

Plan branches and diffs from this tree

```sh
patchula run --dry-run
```

Open or update pull requests for acme/app

```sh
patchula run acme/app
```

Every repository the token reaches

```sh
patchula run --all-repos --config-dir overrides
```

## `patchula serve`

- **Usage:** `patchula serve [FLAGS]`

Run the API-only GitHub App webhook server.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--settings <FILE>` | Operator settings file; also PATCHULA_SETTINGS. | |
| `--listen <ADDR>` | Server bind address; also PATCHULA_LISTEN (default 127.0.0.1:8080). | |
| `--cache <DIR>` | Server cache and queue directory; also PATCHULA_SERVER_CACHE. Default: `patchula/server` in the user cache directory. | |
| `--app-id <ID>` | GitHub App ID; also PATCHULA_APP_ID. | |
| `--private-key-file <FILE>` | PEM private key file; also PATCHULA_APP_PRIVATE_KEY_FILE. | |
| `--webhook-secret-file <FILE>` | Webhook secret file; also PATCHULA_WEBHOOK_SECRET_FILE. | |
| `--shutdown-timeout-secs <SECS>` | Graceful server drain deadline; also PATCHULA_SHUTDOWN_TIMEOUT_SECS (default 60). | |
| `-h --help` | Print help | |

### Examples

Serve with operator settings

```sh
patchula serve --settings settings.pkl
```

Listen on every interface

```sh
patchula serve --settings settings.pkl --listen 0.0.0.0:8080
```

## `patchula tools`

- **Usage:** `patchula tools <SUBCOMMAND>`

Manage the lockfile runner’s tool store (`PATCHULA_TOOLS_DIR`, or `tools/` in the cache directory).

### Flags

| Flag | Description | Default |
| - | - | - |
| `-h --help` | Print help | |

### Examples

Install the pinned toolchains, e.g. in an image

```sh
patchula tools install
```

Drop versions unused for two weeks

```sh
patchula tools prune --days 14
```

## `patchula tools install`

- **Usage:** `patchula tools install [--cache <DIR>]`

Install the pinned lockfile toolchains ahead of time, e.g. in an image build.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--cache <DIR>` | Cache directory, holding the tool store. Default: `patchula` in the user cache directory. | |
| `-h --help` | Print help | |

## `patchula tools prune`

- **Usage:** `patchula tools prune [--cache <DIR>] [--days <DAYS>]`

Uninstall tool versions no run has used recently; pinned defaults stay.

### Flags

| Flag | Description | Default |
| - | - | - |
| `--cache <DIR>` | Cache directory, holding the tool store. Default: `patchula` in the user cache directory. | |
| `--days <DAYS>` | Remove versions unused for at least this many days. | `30` |
| `-h --help` | Print help | |

## `patchula tui`

- **Usage:** `patchula tui [FLAGS] [OWNER/REPO]…`

Browse dependencies and updates in the terminal; with no repository, apply selected updates to the working tree.

### Arguments

| Argument | Description | Default |
| - | - | - |
| `[OWNER/REPO]…` | Repositories as owner/repo, read through the GitHub API; omit for the checkout here. | |

### Flags

| Flag | Description | Default |
| - | - | - |
| `--all-repos` | Process every repository the token can reach instead of naming them. | |
| `--cache <DIR>` | Cache directory, shared by every checkout. Default: `patchula` in the user cache directory (`~/Library/Caches` on macOS, else `XDG_CACHE_HOME` or `~/.cache`). | |
| `--settings <FILE>` | Operator settings file; also PATCHULA_SETTINGS. Default: `patchula/settings.pkl` in the user config directory (`XDG_CONFIG_HOME` or `~/.config`), when it exists. Keeps the run on this machine; a server uses its own settings. | |
| `--concurrency <N>` | Maximum concurrent repository scans (1–100), overriding the settings file; HTTP limits are per host. Default: 8. | |
| `--config <FILE>` | Local Pkl override applied to every selected repository. | |
| `--default-config` | Use the Count’s defaults when the working tree has no `patchula.pkl`, instead of asking. Conflicts with `--config` and `--config-dir`. | |
| `--config-dir <DIR>` | Per-repository overrides: `DIR/<owner>/<name>.pkl`, then `DIR/<name>.pkl`; other repositories use their own `patchula.pkl`, or are skipped without one. Conflicts with `--config`. | |
| `--remote` | Run on a Count Patchula server (PATCHULA_SERVER, or the one found for this checkout) with its credentials and caches; local config, cache and HTTP flags don’t apply. | |
| `--here` | Run on this machine, even if you chose to run this checkout on a server. | |
| `--once` | Print a plain-text snapshot of the updates and exit with `lookup`’s exit code, for pipes and CI logs. | |
| `-h --help` | Print help | |

### Examples

Pick updates and apply them here

```sh
patchula tui
```

Browse a repository through the API

```sh
patchula tui acme/app
```

Print a plain snapshot, for pipes and CI logs

```sh
patchula tui --once
```
