Declarative settings
istota snapshot exports application settings as a plan that istota apply can inspect and reconcile. Use an initialized install and name its configuration with -c or ISTOTA_CONFIG_PATH.
istota -c /data/config/config.toml snapshot -o settings.toml
istota -c /data/config/config.toml apply -f settings.toml --dry-run
istota -c /data/config/config.toml apply -f settings.toml
Apply exits 0 for unchanged settings, 2 for changes made or proposed by a dry run, and 1 for refusal or execution failure. Snapshot exits 0 after writing the complete document and 1 on refusal. Automation must accept apply's exit 2 as success.
What a snapshot contains
A snapshot includes the raw configuration document, live shared and group briefing definitions, and every stored user's restorable profile fields, folder resources, briefing schedules and ordered blocks/sources, scheduled jobs from CRON.md, heartbeat definitions from HEARTBEAT.md, and provisionable credential declarations. It includes explicit defaults and empty collections so a destination can clear stale values.
It omits task and delivery history, generated briefing content, heartbeat history, native login identities, WhatsApp enrollment, consent, credential values and deployment inputs. Referenced scripts, prompts and workspace files are not bundled. Use the backup and migration tools for recovery or a whole-install move; a settings plan cannot reconstruct a VM, remote accounts or runtime databases.
Snapshot reads definitions without initializing stores, seeding profiles or updating credential access timestamps. It checks definitions and file revisions again in fresh reads, retries the complete gather once if they changed, and refuses a second change with state_changed. This detects concurrent settings edits; it is not a coordinated database backup. A missing optional briefing database is empty. A corrupt store, pending definition migration or unmaterialized configuration user is a refusal, not an empty export.
Output and scope
istota -c /data/config/config.toml snapshot --format json -o settings.json
istota -c /data/config/config.toml snapshot --user alice --user bob
istota -c /data/config/config.toml snapshot --no-meta
TOML is the default. Without -o, or with -o -, the document goes to stdout; diagnostics go to stderr. A file is replaced atomically with mode 0600 only after gathering and validation succeed. Non-regular output files and symlinks are refused. Unchanged settings produce the same bytes in the same format.
--user is repeatable. It exports only the named users and omits instance configuration and shared/group briefing definitions. A scoped snapshot warns about shared briefing references that need definitions at the destination. Unknown users are refused. Apply's --user likewise selects declared users and excludes instance sections.
The stable metadata identifies the document as a snapshot. Profiles use profile_mode = "update", so existing managed-field locks survive. Snapshot metadata preserves the destination's configuration ownership marker. --no-meta removes that metadata; applying such a document uses ordinary plan ownership defaults. To adopt settings as managed configuration, explicitly set meta.managed = true and select profile_mode = "managed" for the profiles to manage.
Missing fields and pruning
An absent section is untouched. An absent user is never deleted. Profile updates affect only supplied fields; explicit empty strings, lists, maps and false values reset fields where the domain permits them. Configuration is a whole-document replacement, so omitted configuration fields take loader defaults.
Named collections merge by identity. Briefing blocks and sources use their array positions: supplied entries replace the corresponding prefix, and existing tails survive unless pruning is enabled. Supplied block options and source configuration replace those mappings in full.
istota -c /data/config/config.toml apply -f settings.toml --dry-run --prune --format json
istota -c /data/config/config.toml apply -f settings.toml --prune
--prune removes undeclared definitions only within supplied collections. It preserves users, profiles, organizer-owned resources, module jobs, archives and runtime history. It refuses removals that retained references or configuration seeds would undo. A populated destination needs pruning for exact collection restoration. Ordinary pruning preserves every credential.
Heartbeat snapshots use reset lists to restore inherited cooldown and interval settings. A file-watch check can also reset max_age_hours to remove its age limit. Apply removes this plan metadata before writing HEARTBEAT.md. It writes CRON.md without synchronizing the scheduler database; the scheduler loads changes on its normal pass. Unchanged dispatch keeps a suspended job suspended.
Credentials
Nonempty recognized credential leaves in raw configuration become <unchanged>. An apply on the source preserves the stored value. A destination without that value refuses the plan until a private sidecar supplies a replacement. Empty credential values remain empty. Deployment-file credentials keep their existing writer; a sidecar cannot move them inline.
A snapshot refuses nonempty recognized credential fields in stored briefing block options, per-user source configuration and shared source configuration. The error names the field without its value, and no document or replacement file is written. Remove the embedded credential or configure it through the service's supported credential-store interface before retrying. Folder extras with credential fields are also refused.
The snapshot lists provisionable user service/key slots without decrypting them. Vault, generated and session credentials are excluded and reported on stderr. Missing slots without supplied values produce apply warnings; they do not create placeholder credentials.
A private TOML or JSON sidecar has optional users and config sections. User values map user → service → key → nonempty string, and must match declared slots. Configuration replacements are a list of objects with a segment-array path and a value. Integer path segments address array entries, while a dotted header name is one string segment. Set mode 0600 and keep the sidecar outside shared workspace content.
chmod 600 private-settings.json
istota -c /data/config/config.toml apply -f settings.json --secrets-file private-settings.json --dry-run
istota -c /data/config/config.toml apply -f settings.json --secrets-file private-settings.json
--prune-secrets requires --prune and removes eligible slots only in services explicitly named by a selected user's secret declarations. keys = [] requests removal of that service's eligible slots. Missing services and secrets = [] remove no credentials. Vault, OAuth/session and generated credentials remain outside this scope.
Snapshots are private settings files. Addresses, names and paths remain present. Prompts and commands are operator-written text; snapshot does not scan or rewrite them for secrets. Review a snapshot before sharing it or committing it to a repository.
Moving selected paths
Both commands accept repeated --patch SOURCE=DEST arguments. Quote placeholders to prevent shell expansion.
istota -c /data/config/config.toml snapshot --patch '/data/workspace=${WORKSPACE_ROOT}' -o settings.toml
istota -c /data/config/config.toml apply -f settings.toml --patch '${WORKSPACE_ROOT}=/data/workspace' --dry-run
Patches rewrite declared path fields, including resource paths, job prompt files and file-based heartbeat or briefing sources. They do not rewrite commands, prompt bodies, URLs, credentials or arbitrary strings. Matching uses path boundaries and the longest source prefix. Each value is rewritten once; patches do not cascade. An unmatched prefix produces a warning.
A plan containing database or file sections cannot move the running install's storage roots. Complete that deployment migration first, then patch the plan to the destination's actual roots and preview it there.
Validation and failures
apply --check --json validates structure and configuration types without reading live settings. Use --dry-run to check identities, references, destination paths and credentials. --format json on ordinary apply reports operations, counts, warnings, errors, partial completion and whether successful changes require a restart.
Preflight failure writes no settings. Execution uses separate database transactions and atomic file replacements, so a later failure may leave earlier sections committed. Such a run exits 1 with partial = true and names completed, failed and skipped units. Rerun after resolving the error to converge. --continue-on-error permits later independent users to proceed after a runtime failure; it does not bypass preflight or stale-state refusals. Direct CLI apply reports restart requirements; it does not restart the daemon itself.
On the stack
On the VM, istota-stack apply settings.json --secrets-file private-settings.json runs the same apply in a one-shot container. The plan and the sidecar are copied into a private staging directory, bound read-only, and passed to the container by path; the staging is removed afterwards whatever the outcome. The sidecar, and a --input-format role-vars input, must be private regular files (mode 0600). On a Mac, the local VM's istota-stack apply takes both paths on the Mac and copies them in the same way.
istota-stack apply prints the JSON result document on stdout and its own messages on stderr, and exits as istota apply does. It restarts the stack once when the result says committed changes need a restart. Credential values, briefing content, CRON.md and HEARTBEAT.md changes are reported as changed without a restart, and an unchanged or marker-only apply restarts nothing. A partial apply restarts nothing: the committed changes stay, and the message says to fix the error, apply the plan again and then restart the stack. An image older than the host script returns no result document, which is a failure, never a change; update the stack first.
With Ansible
The management role takes the same plan as istota_plan. --format ansible writes the snapshot as a group_vars file setting that variable, so it goes into the estate's inventory, encrypted, with nothing to edit:
plan=$(ssh vm sudo istota snapshot --format ansible) \
&& printf '%s\n' "$plan" | ansible-vault encrypt --output inventory/group_vars/istota/istota_plan.json -
The snapshot goes into a variable first because a failed snapshot writes nothing to stdout, and piping it straight into ansible-vault encrypt would replace the inventory's plan with an encrypted empty file.
Credentials are set beside it:
istota_plan_secrets:
users:
alice: {karakeep: {api_key: "{{ vault_alice_karakeep }}"}}
Credentials stay in the vault and reach the plan through istota_plan_secrets, the sidecar in variable form. Host settings, deployment secrets and the admins list keep their own role variables; a snapshot does not contain them, so it is not a complete inventory. The config is managed, and read-only in the web config editor, only when the plan sets meta.managed = true; the role adds no metadata of its own. istota_plan_prune and istota_plan_prune_secrets pass --prune and --prune-secrets. Under ansible-playbook --check the role runs the same dry run and reports per-user drift without writing anything or restarting the stack. The variables it took before istota_plan (istota_config, istota_users and the rest) are retired, and a play that still sets one fails before it changes anything.
A settings plan applied by the role is a settings import, not a recovery. To move a whole install, use the backup, restore and migration tools.
Group briefing definitions
[[group_briefings]] entries are identified by group_id and name. They carry title, cron, timezone, channel, enabled state, generation mode/settings and excluded_user_ids. Supply --actor USER for changes: the current owner of an ordinary group or an admin for All users. A new definition must be a disabled draft. An existing definition can be enabled only after its source approvals and any migration cutover checks pass. A saved target cannot move to another group.
The adapter checks live authority and saved-state preconditions in the write transaction. It cannot manufacture contributor grants. Omitted fields preserve existing values; excluded_user_ids = [] explicitly clears exclusions. New exclusions must be current members, while already excluded departed users may remain. --prune retains group definitions and history; disable unwanted definitions explicitly.
Snapshots include definitions without creator attribution, revisions, grants, editions or delivery state. Restore into existing target groups as disabled drafts and obtain fresh approvals where required. Legacy default-template authoring receives a migration diagnostic; it cannot restart per-user seeding. See Migrating group briefings.