Skip to main content
Save a configured tool as a named preset and evolve it across versions. A preset is a versioned, named wrap of a tool. It bakes some of a base tool’s arguments as fixed constants and exposes the rest under a new name. Every preset is versioned — it rides the platform’s versioning spine, so every save appends a version, one version is active, and you can roll back. A preset is always a durable, store-backed record. A preset body is small — a base tool and the fields to bake:
examples/presets/minimal_preset.yaml

​
Create a preset

Name the base tool and the fixed kwargs to bake. The baked keys are removed from the exposed schema; the remaining arguments keep the base tool’s real typed schema. Create writes the durable store row and then registers the live tool.
List presets and read one back:
To check a draft before committing it — the same pre-write validation the create route runs, but without writing — dry-run it with validate:

​
Save a new version

Save a new version when the configuration changes. Omitted fields carry forward from the active version; --clear-tags and --extensions '[]' send the explicit clear sentinel.
Inspect the history and one version:

​
Roll back

Make a prior version active again. Rollback appends a new version pointing at the target body — it never rewrites history.

​
Tag a version

Label an immutable version body without rebinding the tool. Passing no tags clears them to [].

​
Rename a preset

A preset’s name is its live tool name, so renaming it rebinds the tool — the new name binds before the old is torn down. First check whether other presets compose this one (their authored-agent specs name it as a tool); a rename blocks with a 409 listing every referee until you update them:
The versioning spine is one mechanism, shared by many kinds. Presets, access-control policies, and authored agents all ride it — append-only versions, an active pointer, rollback, per-version tags, and rename over an opaque body.
The full subcommand set — including validate, referees, set-version-tags, and rename:
examples/presets/presets_help.sh

​
See also