ferraus plugin state save

Save a plugin's native state as base64 JSON

Synopsis

ferraus plugin state save <name> [options]

Loads the plugin, applies --state, --preset, and --param values, and writes the plugin's native state blob (base64) with the resolved parameters to a JSON file. Pass that file to --state on 'plugin run' or 'render' to reproduce a sound exactly.

Examples

Save a preset as a reusable state file

ferraus plugin state save "Surge XT" --preset "Warm Pad" -o pad.state.json

Save state after setting a parameter

ferraus plugin state save com.acme.eq --param cutoff=2.5kHz -o eq.json

Start from a saved state, darken it with a normalized value, and save a new state

ferraus plugin state save Dexed --state base.state.json --param "Cutoff=norm:0.4" -o dark.state.json

Options

Flag	Type	Default	Meaning
`<name>`	text	—	Plugin name, id, or path to a .clap/.vst3 bundle (path#plugin.id picks one plugin in a bundle) Required.
`--param`	text	—	Set a parameter: name=value, by display name or stable id; value in display units (cutoff=2.5kHz, mix=30%, gain=-6dB) or normalized (norm:0.3) Repeatable.
`--preset`	text	—	Load one of the plugin's presets by name (see 'plugin presets list') before applying --param values
`--state`	path	—	Restore native plugin state from a file written by 'plugin state save' (or a sidecar) before the preset and --param values
`--watchdog`	time	—	Stop the plugin host after this long without progress (default 60s, or FERRAUS_PLUGIN_WATCHDOG_S)

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Code	Meaning
0	Success
1	Processing failed
2	Usage or parameter error
3	Input missing or unreadable
7	Plugin crashed, timed out, or was not found
8	Cancelled
70	Internal error (bug)

Common mistakes

Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

MCP tool: ferraus_plugin_state_save
Schema: ferraus schema plugin state save
Pipeline: { op: plugin state save, args: { ... } } (flag names with _ instead of -)
fx stage: no

{"command": "plugin state save", "defaults": {}}