Maleta.dev
Open app

Search documentation

    / documentation

    Account and device

    Authorize this computer, attach a Maleta from your account, and read the local state without giving up the local-first flow.

    #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

    CommandEffect
    maleta login [--name label]Authorizes this computer with a short code.
    maleta logoutRevokes 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 detachEnds the link without removing files.
    maleta statusCombines 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

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

    1. Read the code

      The CLI prints Abra: with the full URL, Código: with the short code, then Aguardando autorização….

    2. 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=1 disables that attempt.

    3. Attach a Maleta

      Once authorization arrives, the CLI writes the credential, syncs the device id into the state, and prints Agora vincule uma Maleta: maleta attach <maleta>.

    #Refusals before authorization

    ConditionMessage and exit code
    A credential already exists in the file.[error] este computador já tem uma credencial; rode 'maleta logout' primeiro; exit 3.
    MALETA_DEVICE_TOKEN is set.[error] MALETA_DEVICE_TOKEN está definida; remova-a para autorizar este computador; exit 3.

    #Login endings

    EndingResult
    AuthorizedWrites the credential, prints a confirmation starting with [ok] dispositivo autorizado:, and returns 0.
    Code expired[error] o código expirou; rode 'maleta login' de novo; exit 1.
    Denied in the app[error] autorização recusada no app; exit 1.
    Ctrl+C or termination[error] login interrompido; 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.

    #Attach a Maleta

    bash
    maleta attach <maleta>

    The selector is resolved among the account's Cloud Maletas: a UUID selects by exact id, while any other text selects by slug. If multiple Maletas share the same slug, the server refuses with an ambiguous conflict: [error] mais de uma Maleta com este nome; use o id: maleta attach <id>.

    #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

    bash
    maleta detach
maleta logout
    CommandBehavior
    detachRemoves the link on the server, keeps the credential, and moves the resources to pending for maleta prune. No file is deleted.
    logoutTries to revoke on the server, deletes the local credential, removes the local link, and leaves the resources for maleta prune. A revoke failure only prints [warn] não foi possível revogar no servidor; revogue em app.maleta.dev.

    #Read the status

    bash
    maleta status

    The 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:

    LineMeaning
    device:Name from the session; falls back to the credential's id or não autorizado. May include the shortened local id.
    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 nenhuma vinculada.
    applied:Last applied revision and the time saved locally. 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: nada.
    watch:Prints watch: parado or reports rodando with the local lock's PID.