> ## Documentation Index
> Fetch the complete documentation index at: https://piloop.autoresearch.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading

> Upgrade the CLI, the skills and the database with one command.

```bash theme={null}
piloop upgrade
```

The command prints each step as it runs it:

1. It upgrades the CLI with `uv tool upgrade --reinstall-package piloop piloop`, from the source that you installed
   it from: PyPI (the latest release), the GitHub repo (the latest `main`), or a local checkout. It prints the version
   before and after.
2. It runs `piloop install-skills` from the new code, so the skills of every harness on your `PATH` match the new CLI.
   A running harness reads them at its next session.
3. It restarts a running daemon in place, as `piloop restart` does. The running agents continue. The new code
   migrates the database as it starts, and connects to the agents again. When no daemon runs, the upgrade migrates the
   database itself, and the daemon stays stopped.
4. It runs `piloop doctor`. When a check fails, the upgrade exits with a non-zero status.

`piloop --version` prints the version, for example `piloop 0.1.0`. For an install from the GitHub repo, it also
prints the commit, for example `piloop 0.1.0 (a1b2c3d)`.

## Check the install

`piloop doctor` is read-only. You can run it at any time. It checks that:

* The daemon runs the installed code.
* The database has the current schema.
* `PILOOP_SECRETS_COMMAND`, when it is set, runs and prints `NAME=value` lines. The check shows the names only.
* The `piloop.toml` of every project loads.
* The commands of each project's stdio MCP servers are on your `PATH`, and the variables that its servers need are
  set. The check does not start the servers.
* Every harness on your `PATH` has the skills of this CLI.
* The harnesses that your projects use are on your `PATH`.
* For a project with `runtime = "herdr"`: Herdr is installed, the piloop session answers, and Herdr's hooks are
  current for the harnesses of that project.

Each failure says how to fix it, often with the command to run.

## The database

The daemon, and every command that reads or writes projects (such as `init`, `status`, `inbox` and `watch`), migrates
the database to its own schema when it starts. `piloop doctor` and `piloop sql` do not. You never recreate the
database by hand. `piloop migrate` migrates it and prints what changed, for example `schema: 0001 → 0002`.

An older piloop refuses to open a database that a newer one migrated, and tells you to run `piloop upgrade`.

## Deprecated configuration keys

When a release renames or removes a key of `piloop.toml`, the old key keeps working for at least one minor release.
Each use shows a `PiloopDeprecationWarning` with the file, the line, the new key and the release that removes the old
one. The [changelog](https://github.com/hiloopai/piloop/blob/main/CHANGELOG.md) lists every deprecation.

## Other install types

* A checkout that you installed with `uv sync` is not a uv tool. Upgrade it with `git pull`.
* Entire has its own installer. Run it again to upgrade Entire:
  `curl -fsSL https://entire.io/install.sh | bash`.

## When something fails

An unexpected error prints a short message without the traceback. Set `PILOOP_DEBUG=1` to see the full traceback.
Then run `piloop doctor`.

## What is stable

Before 1.0, a minor release may contain breaking changes. These interfaces change only with an entry in the
[changelog](https://github.com/hiloopai/piloop/blob/main/CHANGELOG.md):

* The `piloop` CLI: its commands and their flags.
* The keys of `piloop.toml`. A renamed or removed key keeps working, with a warning, for at least one minor release.
  See [Deprecated configuration keys](#deprecated-configuration-keys).
* The contract of the [evaluate command](/concepts/projects#the-evaluate-command): the `METRIC <name>=<value>` lines,
  the exit status and the per-unit results file.
* The [database schema](/reference/schema), as `piloop sql` shows it. Each release migrates the database forward
  automatically.

The Python import API (the modules of the `piloop` package) is not stable. It can change in any release. To script
piloop, use the CLI and `piloop sql`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.