#What the CLI does
The maleta CLI runs locally: it reads a maleta.json manifest, validates the selection, and materializes skills and plugins in the selected environment. The accepted surface has three parts: the five local commands init, validate, install, sync, and tray; help, triggered by bare maleta, by maleta help, or by --help/-h in any position, which exits with code 0 (a near-typo command name is still a usage error); and the seven device commands of the optional account: login, logout, attach, detach, status, watch, and prune.
| Command | Purpose | Default file |
|---|---|---|
init | Creates a new minimal manifest. | maleta.json |
validate | Reads and validates the manifest without network access. | maleta.json |
install | Resolves the selection and installs skills and plugins. | maleta.json |
sync | Applies the selection again, detecting plugins that are already installed. | maleta.json |
tray | Starts the maleta.dev tray icon in the background. Its menu has an Open at startup checkbox and Quit. | — |
#Device commands (optional account)
The seven device commands form a second surface, opened by maleta login. They talk to the HTTP API at app.maleta.dev, store the credential and the record under ~/.maleta/, and each one exits with one of the same five exit codes as the local commands.
| Command | Purpose | Docs |
|---|---|---|
login | Authorizes this computer on the account, opening the browser with the device code. | cli/device |
logout | Revokes this computer's credential and clears the local binding. | cli/device |
attach <maleta> | Binds a Maleta from the account to this computer. | cli/device |
detach | Removes the binding without deleting the credential. | cli/device |
status | Shows the device, the binding, and what is pending. | cli/device |
watch | Applies the bound Maleta's changes in a loop, never removing anything. | cli/watch |
prune | Removes the files the Maleta wrote that it no longer uses. | cli/watch |
Every bound computer keeps its record in ~/.maleta/state.json, a local install record in ~/.maleta/local-state.json, and its credential in ~/.maleta/credentials.json; see Device state for the complete schema and read guarantees.
#Help and options
With no arguments, with maleta help, or with --help or -h in any position, the CLI prints help and exits with code 0. --file <path> applies to local commands and defaults to maleta.json relative to the current directory when omitted. Flags also accept the joined spelling --file=path / --tool=value; a repeated flag exits 2 with duplicate --file or duplicate --tool, and any stray positional word exits 2 with unexpected argument '<x>'.
| Flag | Available for | Rule |
|---|---|---|
--file <path> | init, validate, install, sync | The value cannot be empty or start with -. Also accepted as --file=path; a duplicate is a usage error. |
--tool all|claude|codex|agents | install, sync (ignored by validate) | Selects the target environment for the run without editing maleta.json. Also accepted as --tool=value; a missing value fails with --tool requires a value and a duplicate with duplicate --tool. |
--dry-run | install, sync, prune | Performs no network writes or disk changes. For prune, previews candidate files. |
--name <label> | login | Label for this computer (1 to 80 printable characters). Defaults to hostname. |
--interval <seconds> | watch | Polling cadence as a plain decimal integer of seconds. 0x10, 1e3, 10.0, 0 and -5 are usage errors; below the 10 s floor or above the 300 s ceiling it warns and uses the bound. |
--once | watch | Runs a single reconciliation pass and exits. |
--yes | prune | Authorizes deletion of unreferenced files written by Maleta. Defaults to dry-run without it. |
--help / -h / help | Any position | Prints help and exits with code 0. |
#Typical flow
Create
maleta initcreates the file if it does not exist yet.Check
maleta validatevalidates the JSON and displays the seven-line summary.Install
maleta installresolves the sources and applies the selection to the targets.Sync
maleta syncrepeats the pipeline after detecting installed plugins.
maleta - local Maleta selection CLI
Usage:
maleta init [--file path]
maleta validate [--file path]
maleta install [--file path] [--tool all|claude|codex|agents] [--dry-run]
maleta sync [--file path] [--tool all|claude|codex|agents] [--dry-run]
maleta lock [--file path] [--dry-run]
maleta tray
maleta --version
Device commands (optional account):
maleta login [--name label] authorize this computer (code at app.maleta.dev/device)
maleta logout revoke the credential and stop following the Maleta
maleta attach <maleta> follow one of your account's Maletas on this computer
maleta detach stop following the bound Maleta
maleta status show what this computer follows and what is pending
maleta watch [--interval seconds] [--once]
apply changes from the bound Maleta (never removes anything)
maleta prune [--dry-run] [--yes] remove only the files this Maleta wrote and no longer needs
maleta tray starts the maleta.dev tray icon in the background. It checks npm at startup and every 24 hours, then restarts after a verified update.
The file targetTool is used when --tool is omitted. targetOs must match the local host.
maleta lock pins every GitHub skill to the commit its ref (or default branch) points at today, so later installs get the same files.
GitHub skills are resolved from the declared public repository/path/ref without executing repository content.
#Quick references
See maleta init, maleta validate, maleta install, maleta sync, maleta tray, cli/device, and cli/watch. Complete exit codes are listed in Exit codes and the local state format in Device state.