Retornatus

CLI reference

Intention-oriented commands. Run from the governed project (or pass --path).

retornatus --help
retornatus gate --help
retornatus skill --help

Continuity

CommandPurpose
initCreate .retornatus/ and append ignore rules for the local index, cache, private keys, and .env files
init --preset <name>Write a packaged config preset. Does not replace an existing config.toml unless --force-config is set
init --list-presetsList packaged presets and exit
init --preset <name> --force-configReplace an existing config.toml with that preset. --force alone, with no preset, still writes the minimal config
preset show <name> / preset listPrint one preset's rendered config, or list presets. See Presets
integrateHub skill + detected Environment bridges
integrate --hooksAlso install the agent Stop, subagent-stop, session-start, and file-edit hooks. --host selects claude, cursor, or codex. See Agent hooks
integrate --remove-hooksRemove the Retornatus Stop hook and leave other hooks in place
project-initBrownfield map → project/project.md
wake / wake --bridgesReconstruct state; rebuild index; optional bridges
doctorProcess vs Brakes scores + governance hygiene. Warns when [retornatus] version in config.toml differs from the installed package
statusDerived Change status
ops list / ops show / ops runOperational hygiene loops

init appends one delimited block to .gitignore (# retornatus-gitignore:begin through # retornatus-gitignore:end) when that begin marker is missing. The block ignores .retornatus/index/, .retornatus/runtime/ (locks, executions, and cache), .pem, .key, .env, and .env.. It keeps !.env.example and !.retornatus/keys/.pub committable. A second init does not duplicate the block and does not remove lines that were already there. If git already tracks a .pem or .key file, init prints a warning on stderr. --preset still appends that gitignore block. Without --preset, the config stays the minimal file.

--force-config is what replaces an existing config.toml with the selected preset. --force without --preset still recreates the minimal config. It does not apply a preset over a file that is already there. An unknown preset name exits 2 and prints the names in this install. preset show <name> prints the config init --preset would write, including the comment block of suggested commands. The packaged names are python, python-platform, fastapi, django, rag, and worker. See Presets.

Change workflow

CommandPurpose
change classifyCeremony lane QUICK / STANDARD / COMPLEX. --from-diff <base> adds file count, lines changed, and scope-gate sensitive paths
change elicitRequirements analysis / Situation readiness (--answer, --write; exit 1 if insufficient)
change createDemand → Situation → Contract → optional Action/Tasks
change overviewClaims ↔ Evidence dashboard. --format pr prints a markdown pull-request body. --json or --format json prints the verdict envelope
change activateActivate draft Contract
change reopenMaterial Contract version (archive prior)
change learnRecord Learning
change create --task/--depends/--resourceExplicit Task graph
change create --lanePin ceremony lane

Tasks and loop

CommandPurpose
task start / complete / fail / reopenDurable Task lifecycle
loop next / loop next --all-readyReady work projection

Intake

CommandPurpose
intake analyze --promptStage-based prompt analysis; propose Skill with human questions
intake analyze --answer TOPIC=…Record human answers (SPECIALIZATION / NEED / CREATE)
intake analyze --create-skillCreate DRAFT Skill only when create_authorized=true

Skills

CommandPurpose
skill need --prompt / --actionAssess specialization need (Action optional)
skill candidatesList repetition candidates. An empty list is normal. Does not create a Skill
skill accept <id>Approve a pending candidate. Writes a draft SKILL.md, or evolves the skill the candidate named
skill reject <id>Reject a pending candidate. The same theme waits for new occurrences
skill create / list / activate / evolve / exportSpecialization lifecycle (manual create still allowed)

Proof and policy

CommandPurpose
evidence add --claimSelf-reported Evidence (provenance=self_reported). Fine for narrative types
evidence run [options] -- <command…>Run a command (no shell, cwd = project root) and record provenance=executed
checks run -c <C-id>Execute [assurance] required_checks and record Evidence
gate contract / evidence / skill-research / assurance / policy / budgetSTOP gates. --json prints the verdict envelope
gate suppressionsSTOP when added lines contain suppression or skip markers. The default scan includes untracked non-ignored files; --staged and --base do not (--json)
gate scope <C-id>STOP when the diff leaves Task resources or hits denied/sensitive paths (--base, --staged, --json)
gate omissionSTOP when code changed and no Change is in the diff. --pr-author is the pull request login. A listed bot whose files all match [governance.omission.bot_exemption] passes with a warning. See Gates
policy check --effect / --actionALLOW / DENY / REQUIRE_HUMAN. Optional --effect-type, --resource, --command
hooks install / remove / statuspre-commit (suppressions + scope) and commit-msg (reads $1)
hook stop --host HOSTAgent turn-end hook (HOST is claude, cursor, or codex). Reads host JSON on stdin. See Agent hooks
hook subagent-stop --host HOSTSubagent-stop hook. Same reminder as hook stop. See Agent hooks
hook session-start --host HOSTAgent session-start hook. Injects the active Change. See Agent hooks
hook file-edit --host HOSTAgent file-edit hook. Warns when the path leaves the active Change scope. See Agent hooks
verify / verify --receipt / verify --jsonAssurance over Contract DONE. --json prints the verdict envelope
ci commentSticky pull-request markdown from verify --json and gate --json, plus change overview --format pr when --path is set. See GitHub Action
verify --run-checksRun required checks, record Evidence, then verify
verify --allow-self-reportedMigration opt-out: accept self-reported test/build/lint evidence. Does not bypass required checks
receipt keygen / receipt keygen --printWrite the public key into .retornatus/keys/. Private key goes to the user config dir, or stdout for a CI secret
receipt sign --change <C-id>Sign the current Assurance result
receipt verify <path>Check a receipt with the committed public key
action budget <A-id> --max NSet Action attempt ceiling (--clear removes it)
assurance plan / assurance reviewIndependent review path
run / run --assurance / run --strict-policyAssemble ExecutionContext
lesson from-gateLearning from gate failure (+ optional Rule Candidate)

Exit codes

CodeWhen
0Success. Gate passed. verify is SATISFIED. Receipt signature ok
1Gate STOP. verify is not SATISFIED. Signature failed. Known id or file missing
2Usage: invalid id, path outside .retornatus, empty or unusable search text, malformed signing key, invalid receipt JSON

gate and verify keep those meanings for real checks, including when --json is set. A bad id is usage (2), not a traceback. Search treats your text as literal tokens (hyphens and quotes are not FTS operators).

JSON output

verify --json, every gate subcommand --json, and change overview --json (or --format json) write one versioned document to stdout. Labels, warnings, gate findings, and other diagnostics go to stderr. The shape, a worked example, and the schema file are in JSON output.

Receipts

verify --receipt and receipt sign write an Ed25519 receipt under .retornatus/assurance/receipts/. The signature covers the verify verdict. receipt verify checks it with the committed public key.

Someone who held the private key signed that result. The receipt does not prove the agent was sandboxed, and it is not a receipt network.

MaterialWhereCommitted?
Public key.retornatus/keys/<key-id>.pubYes. <key-id> is the SHA-256 fingerprint of the raw public key
Private keyUser config directory, or RETORNATUS_SIGNING_KEY (PEM, base64, or even-length hex)No. Never inside the repo, and never copied there from the environment

receipt keygen writes the public key into the repo and the private key under the user config dir ($XDG_CONFIG_HOME/retornatus or %APPDATA%\retornatus). --print sends the private key to stdout for a CI secret and does not write a key file. retornatus init and receipt keygen warn on stderr if git already tracks a .pem or .key file. Untrack that file. The ignore rules from init keep a later git add from picking up a new one, and they do not ignore .retornatus/keys/*.pub.

An agent that can read the private key can still sign. Keep RETORNATUS_SIGNING_KEY and the config-dir key out of the agent's environment. Cloud and remote agents leave receipts unsigned. Verification needs only the committed public key, so a fresh clone can check a receipt without the secret. Setup for a clean VM: Cloud agents.

Store the private key as a GitHub Actions secret and sign in CI, where the agent that edits the repo does not see it:

- name: Sign verify receipt
  env:
    RETORNATUS_SIGNING_KEY: ${{ secrets.RETORNATUS_SIGNING_KEY }}
  run: retornatus verify C-0001 --receipt

Anyone who clones the repo can run retornatus receipt verify path/to/receipt.json.

Legacy HMAC receipts verify only where the old local key exists. The result is legacy_hmac, portable: false, plus a deprecation warning. That key is not written into the repo.

Problems

CommandPurpose
finding addRecord observation (auto-number)
question open / resolve / reopenQuestion lifecycle

Human boundary

CommandPurpose
decision recordHuman Decision
rule propose / rule activate --decisionRule Candidate → Rule

Inspection

CommandPurpose
inspect <id>Print artifact JSON
search <query>FTS5 over index
execution record / execution listHost execution observations

IDs are stable strings such as C-0001, C-0001/A-001, S-0001, R-0001, D-0001.

← Docs hub Product site →