CLI commands
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
Section titled “Examples”Report updates for the checkout here
patchula lookupPlan branches and diffs, writing nothing
patchula run --dry-runBrowse updates and apply the ones you pick
patchula tuiExit 3 in CI while updates are waiting
patchula apply --checkWrite only GitHub Actions updates
patchula apply --manager github-actionsRun the GitHub App webhook server
patchula serve --settings settings.pkl- Usage:
patchula [FLAGS] [SUBCOMMAND]
Global Flags
Section titled “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. |
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help | |
-V --version |
Print version |
patchula apply
Section titled “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.
| 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
Section titled “Examples”Write every available update here
patchula applyWrite nothing; exit 3 if updates are waiting
patchula apply --checkShow the patch updates as a diff
patchula apply --dry-run --type patchWrite only the actions/* updates
patchula apply --manager github-actions --dependency 'glob:actions/*'patchula auth
Section titled “patchula auth”- Usage:
patchula auth <SUBCOMMAND>
Sign in to or out of a Count Patchula server for --remote.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
Examples
Section titled “Examples”Sign in through the server’s GitHub App
patchula auth login --server https://patchula.example.comForget the token for PATCHULA_SERVER
patchula auth logoutpatchula auth login
Section titled “patchula auth login”- Usage:
patchula auth login [--server <URL>]
Sign in with the server’s GitHub App, replacing any stored token.
| Flag | Description | Default |
|---|---|---|
--server <URL> |
Server URL; also PATCHULA_SERVER. | |
-h --help |
Print help |
patchula auth logout
Section titled “patchula auth logout”- Usage:
patchula auth logout [--server <URL>]
Forget the stored token for a server.
| Flag | Description | Default |
|---|---|---|
--server <URL> |
Server URL; also PATCHULA_SERVER. | |
-h --help |
Print help |
patchula cache
Section titled “patchula cache”- Usage:
patchula cache <SUBCOMMAND>
Inspect the cache directory’s database.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
Examples
Section titled “Examples”Print the cache schema this binary supports
patchula cache schemapatchula cache schema
Section titled “patchula cache schema”- Usage:
patchula cache schema
Print the cache database schema this binary supports; it refuses a cache from a newer one.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
patchula config
Section titled “patchula config”- Usage:
patchula config <SUBCOMMAND>
Inspect and validate Pkl configuration.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
Examples
Section titled “Examples”Find and check this repository’s config
patchula config check .Check one config file
patchula config check patchula.pklSave the schema for your editor
patchula config schema > PatchulaConfig.pklCheck operator settings
patchula config check-settings settings.pklpatchula config check
Section titled “patchula config check”- Usage:
patchula config check <PATH>
Validate a Pkl config file or discover one in a repository directory.
Arguments
Section titled “Arguments”| Argument | Description | Default |
|---|---|---|
<PATH> |
Pkl file or repository directory to check. |
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
patchula config schema
Section titled “patchula config schema”- Usage:
patchula config schema
Print the bundled PatchulaConfig.pkl schema as Pkl source.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
patchula config settings-schema
Section titled “patchula config settings-schema”- Usage:
patchula config settings-schema
Print the bundled PatchulaSettings.pkl operator schema.
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
patchula config check-settings
Section titled “patchula config check-settings”- Usage:
patchula config check-settings <PATH>
Validate an operator settings file without credentials or network.
Arguments
Section titled “Arguments”| Argument | Description | Default |
|---|---|---|
<PATH> |
Settings file to check. |
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
patchula lookup
Section titled “patchula lookup”- Usage:
patchula lookup [FLAGS] [OWNER/REPO]…
Report available updates without writing; with no repository, reads the working tree here.
Arguments
Section titled “Arguments”| Argument | Description | Default |
|---|---|---|
[OWNER/REPO]… |
Repositories as owner/repo, read through the GitHub API; omit for the checkout here. |
| 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
Section titled “Examples”Report updates for the checkout here
patchula lookupRead two repositories through the API
patchula lookup acme/app acme/apiThe same report, as JSON
patchula lookup --jsonLook up on your Count Patchula server
patchula lookup --remotepatchula run
Section titled “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
Section titled “Arguments”| Argument | Description | Default |
|---|---|---|
[OWNER/REPO]… |
Repositories as owner/repo, read through the GitHub API; omit for the checkout here. |
| 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
Section titled “Examples”Plan branches and diffs from this tree
patchula run --dry-runOpen or update pull requests for acme/app
patchula run acme/appEvery repository the token reaches
patchula run --all-repos --config-dir overridespatchula serve
Section titled “patchula serve”- Usage:
patchula serve [FLAGS]
Run the API-only GitHub App webhook server.
| 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
Section titled “Examples”Serve with operator settings
patchula serve --settings settings.pklListen on every interface
patchula serve --settings settings.pkl --listen 0.0.0.0:8080patchula tools
Section titled “patchula tools”- Usage:
patchula tools <SUBCOMMAND>
Manage the lockfile runner’s tool store (PATCHULA_TOOLS_DIR, or tools/ in the cache directory).
| Flag | Description | Default |
|---|---|---|
-h --help |
Print help |
Examples
Section titled “Examples”Install the pinned toolchains, e.g. in an image
patchula tools installDrop versions unused for two weeks
patchula tools prune --days 14patchula tools install
Section titled “patchula tools install”- Usage:
patchula tools install [--cache <DIR>]
Install the pinned lockfile toolchains ahead of time, e.g. in an image build.
| 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
Section titled “patchula tools prune”- Usage:
patchula tools prune [--cache <DIR>] [--days <DAYS>]
Uninstall tool versions no run has used recently; pinned defaults stay.
| 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
Section titled “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
Section titled “Arguments”| Argument | Description | Default |
|---|---|---|
[OWNER/REPO]… |
Repositories as owner/repo, read through the GitHub API; omit for the checkout here. |
| 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
Section titled “Examples”Pick updates and apply them here
patchula tuiBrowse a repository through the API
patchula tui acme/appPrint a plain snapshot, for pipes and CI logs
patchula tui --once© 2026 Sweepy
