The CLI keeps this computer's state in <home>/.maleta. <home> is MALETA_CLI_HOME when the variable is set to a non-empty value; otherwise, it is the home directory reported by the operating system. A relative value is resolved to an absolute path against the current directory.
#Files in .maleta
| File | Contents | Lifecycle |
|---|---|---|
credentials.json | Device credentials in version 1 format. | Created by login and removed by maleta logout. |
state.json | Managed state using schema 1: binding, resources, and per-file ownership proof. | Updated atomically by device commands. |
state.corrupt-<timestamp>.json | Quarantined copy of an invalid or unrecognized state.json. | Created when the CLI can move invalid state out of the active path. |
local-state.json | Local install record (localStateVersion: 1): documents[] of documentPath, targetTool, and resources[] with per-file sha256, bytes, and origin. | Written by install and sync for each absolute document path; re-read by prune. |
watch.lock | JSON containing pid, startedAt, hostname, and the holding command (watch or prune). A payload written before that field existed is read as watch. | Exists while a watch or prune --yes holds the lock; a lock from a stopped process is reclaimed on the next acquisition. |
tray.pid | JSON containing the running tray's pid. | Exists while a tray instance holds the singleton lock; a pid file whose process is dead is reclaimed by the next tray. |
#Device credentials
versionLiteral version of the credentials format.
apiOriginAPI origin associated with the credentials.
deviceIdNon-empty identifier for this device.
tokenNon-empty token used to authenticate the device.
MALETA_DEVICE_TOKEN overrides the file in CI or on headless machines, and MALETA_API_ORIGIN can set the API origin. The environment credential's real identity is learned from the session endpoint and never persisted: the env placeholder is a source marker that must not reach state.json or the screen. A token whose identity differs from the recorded one is refused with exit 3, leaving the record untouched.
#state.json schema
stateVersionLiteral version of the state schema.
deviceIdDevice this history belongs to;
nullafter logout or before the first binding.bindingCloud Maleta followed on this computer and the last applied revision;
nullwhen there is no binding.resourcesResources from the bound Maleta that the CLI currently manages.
pendingRemovalResources no longer listed by the account that await
maleta prune; watch does not remove them.orphanedResources left on disk after detach, logout, or an identity change; they also await
maleta prune.
#Managed resources and files
| Object | Field | Type and meaning |
|---|---|---|
ManagedResource | label | string: label of the plan that produced the resource. |
ManagedResource | name | string: destination directory name and part of the resource identity. |
ManagedResource | skillId | string | null: skill identifier, when present. |
ManagedResource | destination | string: resolved destination directory. |
ManagedResource | files | ManagedFile[]: per-file ownership records. |
ManagedFile | path | string: path relative to the destination, using POSIX separators. |
ManagedFile | sha256 | string: 64-character lowercase hexadecimal SHA-256 hash of the recorded bytes. |
ManagedFile | bytes | integer >= 0: recorded file size. |
ManagedFile | origin | "written" | "adopted": the CLI wrote the file or found the same bytes already present. |
#local-state.json schema
localStateVersionLiteral version of the local install record.
documentsOne entry per absolute
maleta.jsonpath a localinstallorsyncwrote.documents[].documentPathAbsolute path of the recorded document; a relative or non-normalized path makes the record corrupt.
documents[].targetToolThe tool target that run used, used to recompute the plan at prune time.
documents[].resourcesCumulative ownership for that document, in the same shape as the state record.
#Binding record
cloudMaletaIdNon-empty identifier of the bound Cloud Maleta.
documentIdNon-empty identifier of the materialized document.
nameDisplay name of the bound Maleta.
appliedRevisionMaterialized revision;
0means nothing has been applied yet.appliedStatusconflictmakes the next watch fetch and retry the revision.appliedAtRecorded timestamp for the application state.
#Proof before removal
Ownership is tracked per file. origin: "written" proves that the CLI created or updated the file; it is removed only if it is still a regular file, remains inside the destination, and its SHA-256 still matches sha256.
origin: "adopted"marks bytes that already existed and matched; the CLI never removes that file.- A modified file, symlink, unsafe path, or unrecorded entry blocks removal of the resource.
- Directories are removed only when empty; user-added contents remain.
maleta watchonly records candidates inpendingRemoval; onlymaleta prune --yesremoves them.
#Missing or invalid state
A missing or unreadable state.json is not treated as empty history: state becomes untrusted and all removal is disabled. Invalid JSON or an unrecognized schema is moved, when possible, to state.corrupt-<timestamp>.json.
#Logout and detach
| Command | Credentials and binding | Resources |
|---|---|---|
maleta logout | Attempts to revoke the session, removes credentials.json, and sets deviceId and binding to null. | Moves resources and pendingRemoval to orphaned; it does not remove destination files. |
maleta detach | Always contacts the server, then sets binding to null and keeps the credentials and deviceId. | Moves resources and pendingRemoval to orphaned; it does not remove destination files. |