# Getting started

> Take one repository from nothing to its first update pull requests.

This page takes one repository to its first update pull requests. You need a GitHub token and [mise](https://mise.jdx.dev).

The fastest way is to give a coding agent in your repository this prompt:

```text
Fetch https://raw.githubusercontent.com/sweepies/count-patchula/main/docs/agent-setup.md and follow its instructions to set up Count Patchula for this repository.
```

The agent checks for a Renovate config to migrate, asks how you want to run the Count, and sets him up. It asks before each decision and never asks for secrets. The steps below do the same by hand.

An agent reading these docs can start from [llms.txt](https://count-patchula.sweepy.dev/llms.txt), which lists every page. Each page is also served as Markdown to a request with `Accept: text/markdown`, or at its URL followed by `index.md`.

1. ### Install patchula

   ```sh
   mise use -g --minimum-release-age 0 packslip:sweepies/count-patchula
   patchula --version
   ```

   mise verifies the download against the release’s signed manifest. Other options are under [installation](https://count-patchula.sweepy.dev/installation/).

2. ### Add a config

   The Count only visits repositories that invite him. Commit a `patchula.pkl` at the repository root:

   `patchula.pkl`

   ```pkl
   amends "PatchulaConfig.pkl"
   ```

   That is a complete config; everything comes from the schema’s defaults: every manager, exact pins (ranges kept for Cargo, `pyproject.toml`, Bundler and Composer, whose lockfiles hold the version; npm and Bun stay exact), digest pins for actions and images, a 24-hour release-age wait, one PR per update with at most ten ordinary ones open at once (security fixes are not held back by that limit), a dependency dashboard issue, and no auto-merge except for reference data such as CA bundles.

   > **Tip**
   >
   > You don’t need to commit `PatchulaConfig.pkl`; the Count supplies it. Vendor it for editor completion, and check the config locally:
   >
   > ```sh
   > patchula config schema > PatchulaConfig.pkl
   > patchula config check .
   > ```

3. ### Get a token

   Export `PATCHULA_TOKEN` (or `GITHUB_TOKEN` or `GH_TOKEN`). With none set, the Count uses a signed-in [GitHub CLI](https://count-patchula.sweepy.dev/guide/how-it-works/#tokens)’s token.

   - `lookup` and dry runs need any token that can read the repository.
   - Real runs need a GitHub App installation token so GitHub signs the commits; the [App’s permissions](https://count-patchula.sweepy.dev/guide/server/#create-the-github-app) are listed with the server.

   The [GitHub App server](https://count-patchula.sweepy.dev/guide/server/) can mint installation tokens itself.

4. ### Look before you leap

   ```sh
   patchula lookup --json acme/my-app > report.json
   patchula run --dry-run acme/my-app
   ```

   `lookup` lists each repository’s updates, known vulnerabilities, failed lookups and notices, with the counts first; `--json` writes the [JSON report](https://count-patchula.sweepy.dev/reference/report/) instead. `run --dry-run` prints the branches and diffs it would publish, without touching GitHub.

   `-v` adds request counts and phase timings.

5. ### Run it

   ```sh
   patchula run acme/my-app
   ```

   The first run opens one PR per update, up to ten ordinary ones at once (security fixes are exempt from that limit), and a Dependency Dashboard issue that lists the rest. Lockfiles are regenerated with the real tools, which mise installs on first use. A repeat run on an unchanged repository costs one GraphQL query.

   With no repository named, commands use this checkout; see [working tree or GitHub](https://count-patchula.sweepy.dev/guide/how-it-works/#working-tree-or-github).

   To have the updates written into your checkout instead of opened as PRs, run [`patchula apply`](https://count-patchula.sweepy.dev/guide/apply/) there, or pick them one by one in the [terminal UI](https://count-patchula.sweepy.dev/guide/tui/).

   To run him on a schedule, use the [GitHub Action](https://count-patchula.sweepy.dev/guide/github-actions/).

## Run him as a server

The recommended way to run the Count is the [GitHub App server](https://count-patchula.sweepy.dev/guide/server/). It keeps caches warm, batches many repositories together, and acts on webhooks, so a ticked checkbox is handled straight away rather than at the next scheduled run. It idles most of the time, so usage-billed hosts such as [Railway](https://count-patchula.sweepy.dev/guide/server/#hosting-on-railway) are cheap.

## Where to go next

[Configuration](https://count-patchula.sweepy.dev/guide/configuration/)Rules, groups, schedules and limits.

[Branches and PRs](https://count-patchula.sweepy.dev/guide/pull-requests/)What the Count writes and the checkboxes he reads.

[Coming from Renovate](https://count-patchula.sweepy.dev/renovate/compatibility/)If you are switching.

[GitHub App server](https://count-patchula.sweepy.dev/guide/server/)Run him continuously from webhooks.
