Retornatus

Quick start

Get Retornatus running in a project in about ten minutes.

1. Prerequisites

python --version
uv --version

2. Install the CLI

From PyPI (recommended):

uv tool install retornatus
retornatus --version   # 1.9.1

One-shot without a global install: uvx retornatus --help.

From TestPyPI (CI / pre-release dry-run):

uv tool install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  retornatus

--extra-index-url is required so dependencies still resolve from production PyPI.

From Git or a local clone:

uv tool install --force git+https://github.com/luizssantiago92/retornatus.git
# or
uv tool install --force /path/to/retornatus

3. Initialize the project

In the application repository (not necessarily this harness repo):

cd /path/to/your-app
retornatus init
retornatus integrate
retornatus doctor

You should see:

To start from a packaged config instead of the minimal file, run retornatus init --list-presets and then retornatus init --preset fastapi on an empty project. python is pytest, ruff, and mypy. python-platform, fastapi, django, rag, and worker extend that bar. When deploy files, task code, or model paths are part of the Change, verify also expects those commands to have run, plus a short rollback, retry, or fallback note. It checks that the command ran. It does not grade quality. An existing config.toml stays in place unless you pass --force-config. That preset init is an alternative to the minimal init above, not a second step in this walkthrough. Details: Presets.

Optional for brownfield repos:

retornatus project-init
retornatus wake --bridges

4. Create your first Change

Via agent (recommended): open chat and ask it to follow the Retornatus hub skill, for example:

> Create a Retornatus Change for GET /health returning 200. Contract and gates before code.

Via CLI:

retornatus change elicit \
  --demand "Expose a liveness check for ops" \
  --what "GET /health returns 200 with status ok" \
  --done "Automated test covers /health"

retornatus change create \
  --title "Add health endpoint" \
  --demand "Expose a liveness check for ops" \
  --what "GET /health returns 200 with status ok" \
  --done "Automated test covers /health" \
  --objective "Implement and verify health endpoint"

retornatus gate contract C-0001

If Situation is incomplete, use --draft-contract on create, then retornatus change activate C-0001 when ready.

5. Execute and prove

retornatus loop next C-0001
retornatus run C-0001/A-001
# implement in the host…
retornatus evidence run -c C-0001 -t test_result -s "/health" \
  --claim C-0001/claim-done-1 -- python -m pytest -q
retornatus gate evidence C-0001
retornatus verify C-0001

Non-zero gate exit = STOP. Do not treat a chat summary as success.

6. Preserve the return

retornatus change learn \
  --title "Health checks need Claim-bound test_result Evidence" \
  --body "Dogfood: verify failed until --claim was set."
retornatus status

Troubleshooting

SymptomCheck
Not initializedretornatus init
Hub skill missingretornatus integrate
Index empty after crashretornatus wake (rebuilds from files)
Contract gate failsActive Contract with WHAT + DONE
Verify inconclusiveEvidence must SUPPORT the Claim id
Verify UNVERIFIEDTest/build/lint Evidence came from evidence add. Use evidence run, or --allow-self-reported while migrating

More: FAQ · Gates · Tutorial: first Change

← Docs hub Product site →