Skip to content

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.

Report updates for the checkout here

Terminal window
patchula lookup

Plan branches and diffs, writing nothing

Terminal window
patchula run --dry-run

Browse updates and apply the ones you pick

Terminal window
patchula tui

Exit 3 in CI while updates are waiting

Terminal window
patchula apply --check

Write only GitHub Actions updates

Terminal window
patchula apply --manager github-actions

Run the GitHub App webhook server

Terminal window
patchula serve --settings settings.pkl
  • Usage: patchula [FLAGS] [SUBCOMMAND]
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
  • 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

Write every available update here

Terminal window
patchula apply

Write nothing; exit 3 if updates are waiting

Terminal window
patchula apply --check

Show the patch updates as a diff

Terminal window
patchula apply --dry-run --type patch

Write only the actions/* updates

Terminal window
patchula apply --manager github-actions --dependency 'glob:actions/*'
  • Usage: patchula auth <SUBCOMMAND>

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

Flag Description Default
-h --help Print help

Sign in through the server’s GitHub App

Terminal window
patchula auth login --server https://patchula.example.com

Forget the token for PATCHULA_SERVER

Terminal window
patchula auth logout
  • 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
  • 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
  • Usage: patchula cache <SUBCOMMAND>

Inspect the cache directory’s database.

Flag Description Default
-h --help Print help

Print the cache schema this binary supports

Terminal window
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
  • Usage: patchula config <SUBCOMMAND>

Inspect and validate Pkl configuration.

Flag Description Default
-h --help Print help

Find and check this repository’s config

Terminal window
patchula config check .

Check one config file

Terminal window
patchula config check patchula.pkl

Save the schema for your editor

Terminal window
patchula config schema > PatchulaConfig.pkl

Check operator settings

Terminal window
patchula config check-settings settings.pkl
  • Usage: patchula config check <PATH>

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

Argument Description Default
<PATH> Pkl file or repository directory to check.
Flag Description Default
-h --help Print help
  • Usage: patchula config schema

Print the bundled PatchulaConfig.pkl schema as Pkl source.

Flag Description Default
-h --help Print help
  • Usage: patchula config settings-schema

Print the bundled PatchulaSettings.pkl operator schema.

Flag Description Default
-h --help Print help
  • Usage: patchula config check-settings <PATH>

Validate an operator settings file without credentials or network.

Argument Description Default
<PATH> Settings file to check.
Flag Description Default
-h --help Print help
  • Usage: patchula lookup [FLAGS] [OWNER/REPO]…

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

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

Report updates for the checkout here

Terminal window
patchula lookup

Read two repositories through the API

Terminal window
patchula lookup acme/app acme/api

The same report, as JSON

Terminal window
patchula lookup --json

Look up on your Count Patchula server

Terminal window
patchula lookup --remote
  • 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.

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

Plan branches and diffs from this tree

Terminal window
patchula run --dry-run

Open or update pull requests for acme/app

Terminal window
patchula run acme/app

Every repository the token reaches

Terminal window
patchula run --all-repos --config-dir overrides
  • 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

Serve with operator settings

Terminal window
patchula serve --settings settings.pkl

Listen on every interface

Terminal window
patchula serve --settings settings.pkl --listen 0.0.0.0:8080
  • 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

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

Terminal window
patchula tools install

Drop versions unused for two weeks

Terminal window
patchula tools prune --days 14
  • 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
  • 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
  • Usage: patchula tui [FLAGS] [OWNER/REPO]…

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

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

Pick updates and apply them here

Terminal window
patchula tui

Browse a repository through the API

Terminal window
patchula tui acme/app

Print a plain snapshot, for pipes and CI logs

Terminal window
patchula tui --once