Skip to main content
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 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:
  • 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.
  • The contract of the evaluate command: the METRIC <name>=<value> lines, the exit status and the per-unit results file.
  • The database 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.