tauri-plugin-configurate exposes 16 IPC commands that the Tauri frontend can call via invoke("plugin:configurate|<name>", { payload }). Under normal usage you never call these directly — the TypeScript SDK builds the correct payload and invokes the appropriate command for every operation. This reference is intended for advanced users building custom integrations, debugging IPC traffic, or writing alternative client-side SDKs.
All commands listed here are internal implementation details of the TypeScript SDK. The stable public API is the Configurate class and its methods. If you find yourself calling these commands directly, consider opening an issue to discuss whether the SDK is missing a feature you need.
Common payload fields
Most single-config commands accept a ConfiguratePayload object with these fields:
| Field | Type | Description |
|---|
fileName | string | Config file name (no path separators) |
baseDir | number | Tauri BaseDirectory enum value |
provider | object | Provider descriptor — see below |
options.dirName | string? | Replaces the app-identifier directory segment |
options.currentPath | string? | Sub-directory within the resolved root |
data | unknown | Config data to write (write operations only) |
keyringEntries | array? | Keyring entries to read or write |
keyringOptions | object? | { service, account } for keyring access |
withUnlock | boolean | When true, return unlocked data |
returnData | boolean | When true, return the written data |
createIfMissing | boolean | patch only — create if file does not exist |
backup | boolean | Enable rolling backup files before each write |
provider field is an object with a kind field ("json", "yml", "toml", "binary", or "sqlite") plus provider-specific fields (encryptionKey, kdf, dbName, tableName).
Single-config commands
create
IPC name: plugin:configurate|create
Creates a new config entry and writes it to storage. Emits a configurate://change event with operation: "create" on success.
| Payload field | Required | Description |
|---|
fileName | Yes | File name for the new config |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
data | Yes | Initial config data to write |
keyringEntries | With keyringOptions | Secrets to store in the OS keyring |
keyringOptions | With keyringEntries | Keyring service and account |
unknown (the written data when returnData: true, otherwise null).
load
IPC name: plugin:configurate|load
Reads an existing config from storage and returns the raw data. Keyring fields in the stored data are null — use unlock to populate them.
| Payload field | Required | Description |
|---|
fileName | Yes | File name to load |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
unknown — the raw deserialized config data.
save
IPC name: plugin:configurate|save
Overwrites an existing config with data, replacing all stored content. Emits a configurate://change event with operation: "save".
| Payload field | Required | Description |
|---|
fileName | Yes | File name to overwrite |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
data | Yes | Full replacement config data |
keyringEntries | With keyringOptions | Secrets to store in the OS keyring |
keyringOptions | With keyringEntries | Keyring service and account |
unknown (written data when returnData: true, otherwise null).
patch
IPC name: plugin:configurate|patch
Reads the existing config, deep-merges data into it, and writes the result back. Object keys are merged recursively; non-object values are replaced. Emits a configurate://change event with operation: "patch". The file is locked for the full duration of the read-merge-write cycle.
| Payload field | Required | Description |
|---|
fileName | Yes | File name to patch |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
data | Yes | Partial data to merge |
createIfMissing | No | When true, creates the config if it does not exist instead of returning an error |
unknown (merged data when returnData: true, otherwise null).
delete
IPC name: plugin:configurate|delete
Deletes the config file (or SQLite row) from storage. If keyring entries are provided, removes the corresponding secrets from the OS keyring after the file is deleted. Emits a configurate://change event with operation: "delete".
| Payload field | Required | Description |
|---|
fileName | Yes | File name to delete |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
keyringEntries | With keyringOptions | Keyring entries to remove |
keyringOptions | With keyringEntries | Keyring service and account |
null.
exists
IPC name: plugin:configurate|exists
Checks whether the config file (or SQLite row) exists in storage.
| Payload field | Required | Description |
|---|
fileName | Yes | File name to check |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
boolean.
reset
IPC name: plugin:configurate|reset
Deletes the existing config and re-creates it with the provided data. This is an atomic operation within the process — the file lock is held for the entire delete-then-create sequence. Emits a configurate://change event with operation: "reset".
| Payload field | Required | Description |
|---|
fileName | Yes | File name to reset |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
data | Yes | Default data to write after deletion |
unknown (written data when returnData: true, otherwise null).
unlock
IPC name: plugin:configurate|unlock
Reads keyring secrets and inlines them into an already-loaded plain data object. Does not re-read the file from disk — pass in data you have already loaded.
| Payload field | Required | Description |
|---|
data | Yes | Previously loaded plain config data (with null keyring fields) |
keyringEntries | Yes | Entries describing which keyring IDs map to which dot-paths |
keyringOptions | Yes | Keyring service and account |
unknown — the data object with keyring fields populated.
export_config
IPC name: plugin:configurate|export_config
Reads a config and serializes it to a string in the specified format. Supports "json", "yml", and "toml".
| Payload field | Required | Description |
|---|
source | Yes | A ConfiguratePayload identifying the config to export |
targetFormat | Yes | "json", "yml", or "toml" |
string — the serialized config.
import_config
IPC name: plugin:configurate|import_config
Parses a config string from the specified source format and saves the parsed data to the target config location. Emits a configurate://change event with operation: "import".
| Payload field | Required | Description |
|---|
target | Yes | A ConfiguratePayload identifying where to save the imported data |
sourceFormat | With content | "json", "yml", or "toml" |
content | With sourceFormat | The serialized config string to parse |
parseOnly | No | When true, parses and returns the data without writing to storage |
unknown — the imported (parsed) data.
File-watching commands
watch_file
IPC name: plugin:configurate|watch_file
Registers a file-system watcher on the config file. When the file is modified by an external process, a configurate://change event is emitted with operation: "external_change". Only file-based providers are supported — calling this for a SQLite provider returns an error.
| Payload field | Required | Description |
|---|
fileName | Yes | File to watch |
baseDir | Yes | Base directory |
provider | Yes | Must be a file-based provider |
null.
watch_file is not supported for SqliteProvider. Calling it with a SQLite payload returns an invalid_payload error.
unwatch_file
IPC name: plugin:configurate|unwatch_file
Unregisters a previously registered file watcher. Safe to call even if the file is not currently watched.
| Payload field | Required | Description |
|---|
fileName | Yes | File to stop watching |
baseDir | Yes | Base directory |
provider | Yes | Storage provider |
null.
list_configs
IPC name: plugin:configurate|list_configs
Lists config entries in the resolved root directory.
- File-based providers — scans the directory for files matching the provider’s extension. Backup files (
.bak1, .bak2, …) and temp files (.*.tmp) are excluded. Results are sorted alphabetically.
- SQLite — queries all
config_key values from the table.
| Payload field | Required | Description |
|---|
fileName | Yes | Used only to resolve path options; the name itself is not filtered on |
baseDir | Yes | Base directory to scan |
provider | Yes | Storage provider |
string[] — file names or SQLite keys.
Batch commands
Batch commands accept a BatchPayload with an entries array. Each entry has a unique id string and a payload field containing a standard ConfiguratePayload. Duplicate IDs within the same batch are rejected. Results are returned as a map keyed by entry id.
load_all
IPC name: plugin:configurate|load_all
Loads multiple configs in a single IPC call. Each entry is processed independently — one failure does not abort the rest.
| Entry field | Required | Description |
|---|
id | Yes | Unique identifier for this batch entry |
payload | Yes | Standard ConfiguratePayload for the config to load |
BatchRunResult — { results: Record<string, { ok: true; data: unknown } | { ok: false; error: { kind: string; message: string } }> }.
save_all
IPC name: plugin:configurate|save_all
Saves multiple configs in a single IPC call. Change events for all successful entries are emitted after all saves complete.
| Entry field | Required | Description |
|---|
id | Yes | Unique identifier for this batch entry |
payload | Yes | Standard ConfiguratePayload with data included |
BatchRunResult.
patch_all
IPC name: plugin:configurate|patch_all
Deep-merges patch data into multiple configs in a single IPC call. Each entry’s file lock is held for its individual read-merge-write cycle. Change events are emitted after all patches complete.
| Entry field | Required | Description |
|---|
id | Yes | Unique identifier for this batch entry |
payload | Yes | Standard ConfiguratePayload with partial data to merge |
BatchRunResult.