patchula

• Version: 0.1.0

Count Patchula vants to update your deps. A fast dependency update bot for GitHub.

Exit codes: 0 = success; 1 = runtime error; 2 = usage or configuration error.

No interactive prompts are used. Future prompts require both stdin and stdout to be TTYs and use demand.

• Usage: patchula [FLAGS] [SUBCOMMAND]

Global Flags

• --recheck <RECHECK> — Checkbox wording; also PATCHULA_RECHECK. Default: now in server, next-run in CLI.

  Choices: now, next-run

• -v --verbose — Increase diagnostic verbosity; repeat for more detail.

• --color <COLOR> — Control ANSI colors in diagnostics.

  Choices: auto, always, never

  Default: auto

• --json — Emit machine-readable command results and errors (schema stays Pkl).

Flags

• --server — Run the API-only GitHub App webhook server (no subcommand).
• --settings <SETTINGS> — Operator Pkl settings file; also PATCHULA_SERVER_SETTINGS.
• --listen <LISTEN> — Server bind address; also PATCHULA_LISTEN (default 127.0.0.1:8080).
• --server-cache <SERVER_CACHE> — Persistent server cache/queue; also PATCHULA_SERVER_CACHE.
• --app-id <APP_ID> — GitHub App ID; also PATCHULA_APP_ID.
• --private-key-file <PRIVATE_KEY_FILE> — PEM private key file; also PATCHULA_APP_PRIVATE_KEY_FILE.
• --webhook-secret-file <WEBHOOK_SECRET_FILE> — Webhook secret file; also PATCHULA_WEBHOOK_SECRET_FILE.
• --shutdown-timeout-secs <SHUTDOWN_TIMEOUT_SECS> — Graceful server drain deadline; also PATCHULA_SHUTDOWN_TIMEOUT_SECS (default 60).
• -h --help — Print help
• -V --version — Print version

patchula config

• Usage: patchula config <SUBCOMMAND>

Inspect and validate Pkl configuration.

Flags

• -h --help — Print help

patchula config check

• Usage: patchula config check <PATH>

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

Arguments

• <PATH> — Pkl file or repository directory to check.

Flags

• -h --help — Print help

patchula config schema

• Usage: patchula config schema

Print the bundled Patchula.pkl schema as Pkl source.

Flags

• -h --help — Print help

patchula config server-schema

• Usage: patchula config server-schema

Print the bundled PatchulaServer.pkl operator schema.

Flags

• -h --help — Print help

patchula config check-server

• Usage: patchula config check-server <PATH>

Validate an operator Pkl server settings file without credentials or network.

Arguments

• <PATH> — Pkl file or repository directory to check.

Flags

• -h --help — Print help

patchula lookup

• Usage: patchula lookup [FLAGS] [REPOSITORIES]…

Extract dependencies and report available updates without writing repositories.

Arguments

• [REPOSITORIES]… — Repositories as owner/repo; omit to discover all accessible repositories.

Flags

• --cache <CACHE> — Shared SQLite cache path.

  Default: .patchula-cache.sqlite

• --concurrency <CONCURRENCY> — Maximum concurrent repository scans (1–100); HTTP limits are per host.

  Default: 8

• --host-concurrency <HOST_CONCURRENCY> — Override a host's HTTP limit as HOST=LIMIT (1–100); repeat per host. Default: 16.

• --registry-freshness-secs <REGISTRY_FRESHNESS_SECS> — Freshness seconds for OCI tag lists without validators; 0 uses upstream policy.

  Default: 3600

• --go-freshness-secs <GO_FRESHNESS_SECS> — Minimum freshness seconds for Go proxy lists/latest; 0 uses upstream policy.

  Default: 3600

• --config <CONFIG> — Local Pkl override applied to every selected repository.

• --config-dir <CONFIG_DIR> — Per-repository local overrides: <dir>/<owner>/<name>.pkl wins over <dir>/<name>.pkl. Unmatched repositories discover .github/patchula.pkl then patchula.pkl; neither means skipped. All matched files are validated before repository scans. Mutually exclusive with --config.

• --local <LOCAL> — Read one repository from this local directory instead of GitHub. Lookups still reach registries, and nothing is written: use it with lookup or run --dry-run.

• -h --help — Print help

patchula run

• Usage: patchula run [FLAGS] [REPOSITORIES]…

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

Arguments

• [REPOSITORIES]… — Repositories as owner/repo; omit to discover all accessible repositories.

Flags

• --cache <CACHE> — Shared SQLite cache path.

  Default: .patchula-cache.sqlite

• --concurrency <CONCURRENCY> — Maximum concurrent repository scans (1–100); HTTP limits are per host.

  Default: 8

• --host-concurrency <HOST_CONCURRENCY> — Override a host's HTTP limit as HOST=LIMIT (1–100); repeat per host. Default: 16.

• --registry-freshness-secs <REGISTRY_FRESHNESS_SECS> — Freshness seconds for OCI tag lists without validators; 0 uses upstream policy.

  Default: 3600

• --go-freshness-secs <GO_FRESHNESS_SECS> — Minimum freshness seconds for Go proxy lists/latest; 0 uses upstream policy.

  Default: 3600

• --config <CONFIG> — Local Pkl override applied to every selected repository.

• --config-dir <CONFIG_DIR> — Per-repository local overrides: <dir>/<owner>/<name>.pkl wins over <dir>/<name>.pkl. Unmatched repositories discover .github/patchula.pkl then patchula.pkl; neither means skipped. All matched files are validated before repository scans. Mutually exclusive with --config.

• --local <LOCAL> — Read one repository from this local directory instead of GitHub. Lookups still reach registries, and nothing is written: use it with lookup or run --dry-run.

• --dry-run — Print planned branches, files and unified diffs without writing to GitHub.

• --allow-lockfile-pending — Permit manifest-only test branches for unsupported binary bun locks.

• -h --help — Print help

patchula tools

• Usage: patchula tools <SUBCOMMAND>

Manage the lockfile runner's tool store (PATCHULA_TOOLS_DIR, or <cache>.tools).

Flags

• -h --help — Print help

patchula tools install

• Usage: patchula tools install [--cache <CACHE>]

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

Flags

• --cache <CACHE> — Shared SQLite cache path; the tool store sits beside it.

  Default: .patchula-cache.sqlite

• -h --help — Print help

patchula tools prune

• Usage: patchula tools prune [--cache <CACHE>] [--days <DAYS>]

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

Flags

• --cache <CACHE> — Shared SQLite cache path; the tool store sits beside it.

  Default: .patchula-cache.sqlite

• --days <DAYS> — Remove versions unused for at least this many days.

  Default: 30

• -h --help — Print help

patchula tui

• Usage: patchula tui [FLAGS] [REPOSITORIES]…

Browse dependencies and updates in the terminal; with --local, apply selected updates.

Arguments

• [REPOSITORIES]… — Repositories as owner/repo; omit to discover all accessible repositories.

Flags

• --cache <CACHE> — Shared SQLite cache path.

  Default: .patchula-cache.sqlite

• --concurrency <CONCURRENCY> — Maximum concurrent repository scans (1–100); HTTP limits are per host.

  Default: 8

• --host-concurrency <HOST_CONCURRENCY> — Override a host's HTTP limit as HOST=LIMIT (1–100); repeat per host. Default: 16.

• --registry-freshness-secs <REGISTRY_FRESHNESS_SECS> — Freshness seconds for OCI tag lists without validators; 0 uses upstream policy.

  Default: 3600

• --go-freshness-secs <GO_FRESHNESS_SECS> — Minimum freshness seconds for Go proxy lists/latest; 0 uses upstream policy.

  Default: 3600

• --config <CONFIG> — Local Pkl override applied to every selected repository.

• --config-dir <CONFIG_DIR> — Per-repository local overrides: <dir>/<owner>/<name>.pkl wins over <dir>/<name>.pkl. Unmatched repositories discover .github/patchula.pkl then patchula.pkl; neither means skipped. All matched files are validated before repository scans. Mutually exclusive with --config.

• --local <LOCAL> — Read one repository from this local directory instead of GitHub. Lookups still reach registries, and nothing is written: use it with lookup or run --dry-run.

• --once — Print a plain-text snapshot of the updates and exit, for pipes and CI logs.

• -h --help — Print help