#Account is optional
The account adds cloud-side tracking of a Maleta. The local commands init, validate, install and sync keep working without a credential and never touch the device API.
#Commands
| Command | Effect |
|---|---|
maleta login [--name label] | Authorizes this computer with a short code. |
maleta logout | Revokes the credential when possible, ends the local link, and keeps the files. |
maleta attach <maleta> | Attaches a Maleta from the account by id or slug. |
maleta detach | Ends the link without removing files. |
maleta status | Combines the account session with the state saved on this computer. |
maleta watch [--interval seconds] [--once] | Polls and continuously applies the bound Maleta's changes in a loop, never removing anything. |
maleta prune [--dry-run] [--yes] | Removes unreferenced files written by Maleta that are no longer in the bound selection. |
#Authorize with login
maleta login
maleta login --name workstation--name accepts 1 to 80 printable characters. Without the option, the name is the hostname truncated to 80 characters. Unknown options and extra arguments are usage errors that exit with 2.
Read the code
The CLI prints
Open:with the full URL,Code:with the short code, thenWaiting for authorization….Confirm in the app
Open app.maleta.dev/device and confirm the code. The CLI only tries to open the URL automatically on a TTY stdout;
MALETA_NO_BROWSER=1disables that attempt.Attach a Maleta
Once authorization arrives, the CLI writes the credential, syncs the device id into the state, and prints
Now attach a Maleta: maleta attach <maleta>.
#Refusals before authorization
| Condition | Message and exit code |
|---|---|
| A credential already exists in the file. | [error] this computer already has a credential; run 'maleta logout' first; exit 3. |
MALETA_DEVICE_TOKEN is set. | [error] MALETA_DEVICE_TOKEN is set; unset it to authorize this computer; exit 3. |
#Login endings
| Ending | Result |
|---|---|
| Authorized | Writes the credential, prints a confirmation starting with [ok] device authorized:, and returns 0. |
| Code expired | [error] the code expired; run 'maleta login' again; exit 1. |
| Denied in the app | [error] authorization was denied in the app; exit 1. |
| Ctrl+C or termination | [error] login interrupted; exit 1. |
#Credential in the CLI home
The file is <CLI home>/.maleta/credentials.json. By default, the CLI home is the user's home directory; MALETA_CLI_HOME overrides it. The file stores version, apiOrigin, deviceId and token.
MALETA_DEVICE_TOKEN takes precedence over the file and uses MALETA_API_ORIGIN or https://app.maleta.dev. That environment credential is never written to disk nor revoked by logout; remove the variable first.
The environment credential carries no identity of its own — its deviceId is only a source marker — so the real identity is always learned from the session endpoint before it is compared with the record. An identity that genuinely differs from the one this computer recorded is refused with exit 3 and [error] MALETA_DEVICE_TOKEN belongs to a different device than the one this computer last used. Delete .maleta/state.json if you mean to switch devices, or use the original token., leaving the record byte-identical.
Tokens are redacted from every message the CLI echoes: a server message that embeds a mlt_dev_, github_pat_, or gh[pousr]_ value prints it as [redacted].
#Attach a Maleta
maleta attach <maleta>The selector is resolved among the account's Cloud Maletas: a UUID selects by exact id, then an exact slug, and finally a name compared case- and accent-insensitively through the same slug function the CLI uses. If more than one Maleta matches, the server refuses with an ambiguous conflict: [error] More than one Maleta in your account uses that name. Run 'maleta attach <id>' with the Maleta's id. A selector that matches nothing answers [error] No Maleta matches that name, slug, or id. Use the exact name from your account, or attach by id (see app.maleta.dev)..
#Manage devices in the web workspace
The Account page lists all authorized computers associated with your GitHub sign-in, showing device names, bound Maleta, and last seen activity. You can unbind a computer from a Maleta remotely without revoking its credential, or revoke the computer entirely.
#Detach and logout keep the files
maleta detach
maleta logout| Command | Behavior |
|---|---|
detach | Always contacts the server, even when nothing is bound locally (then it prints [ok] this device is now detached; nothing was bound locally). Keeps the credential and moves the resources to orphaned for maleta prune. No file is deleted. |
logout | Revokes the credential when possible, deletes the local credential, clears the binding, and moves the resources to orphaned for maleta prune. A revoke failure only prints [warn] could not revoke on the server; revoke it at app.maleta.dev. An unreadable credentials.json is removed with [ok] removed the unreadable device credential; this computer is no longer authorized instead of blocking recovery. |
#Read the status
maleta statusThe command tries to query the account, but it always answers from the local record when the session is unavailable. It returns 0 and prints these lines:
| Line | Meaning |
|---|---|
device: | Name from the session, followed by the shortened local id. When the account does not answer it falls back to the credential's id, or prints authorized (<short id>) / authorized (offline) for an environment credential, and not authorized with no credential at all. |
origin: | The API origin used by the credential or the current configuration, followed by a connectivity note when needed. |
maleta: | Cloud Maleta and revision; falls back to the local binding when the account does not answer, or shows none bound. |
applied: | Local application state. Prints applied: nothing applied yet until the first maleta watch pass records a real timestamp, then applied: rev N at <timestamp>. Only shown when a local binding exists. |
managed: | Count of managed skills and of files the Maleta wrote. |
pending: | Conflicts, removals, or unlinked resources waiting for action; with nothing pending it prints pending: nothing. |
watch: | Prints watch: stopped, watch: running (pid N), or watch: blocked by 'maleta prune' (pid N) when another command holds the lock. |
A brand-new home has no record yet, which is not an error. Only an unreadable record warns, on stderr: [warn] this computer's record was unreadable and was quarantined to <path>.