#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 or by --help/-h in any position, which always exits with code 0; and the seven device commands of the optional account: login, logout, attach, detach, status, watch, and prune.

Supported commands
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.

Device 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 and its credential in ~/.maleta/credentials.json; see Device state for the complete schema and read guarantees.

#Help and options

With no arguments, 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
Flag	Available for	Rule
`--file <path>`	init, validate, install, sync	The value cannot be empty or start with `-`.
`--tool all\|claude\|codex\|agents`	install, sync (ignored by validate)	Selects the target environment for the run without editing maleta.json.
`--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 in whole seconds (minimum 10 s server floor).
`--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`	Any position	Prints help and exits with code 0.

#Typical flow

Create
maleta init creates the file if it does not exist yet.
Check
maleta validate validates the JSON and displays the seven-line summary.
Install
maleta install resolves the sources and applies the selection to the targets.
Sync
maleta sync repeats the pipeline after detecting installed plugins.

CLI help

text

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 tray
  maleta --version

Device commands (optional account):
  maleta login [--name label]      autoriza este computador (código em app.maleta.dev/device)
  maleta logout                    revoga a credencial e para de seguir a Maleta
  maleta attach <maleta>           segue uma Maleta da conta neste computador
  maleta detach                    para de seguir a Maleta vinculada
  maleta status                    mostra o que este computador segue e o que ficou pendente
  maleta watch [--interval seconds] [--once]
                                   aplica as mudanças da Maleta vinculada (não remove nada)
  maleta prune [--dry-run] [--yes]  remove só os arquivos que a Maleta escreveu e não usa mais

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.
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.

Search documentation

CLI overview