Manifa

Automation & agents

mani is built to be driven by scripts and AI agents, not just typed by hand. Two features make that safe and stable:

  • mani schema describes the whole command surface — every verb, its parameters, its scope, and its result — as JSON, so you discover what a build supports instead of hard-coding it.
  • The --json envelope and exit-code taxonomy let you branch on structured results, never on prose.

The rule of thumb: discover with mani schema, act with mani <verb> --json, and branch on .ok / .error.code and the exit code. Trust the live schema over any documentation when they disagree.

The scope ladder

Every verb in mani schema carries a scope. Read it before you run a command and gate your behavior on it — this is the most important thing an unattended caller does:

  • read_metadata — safe. Reads only non-secret metadata (ids, epochs, counts, status): e.g. vault ls, vault members, status, device ls, env ls, account id, org invites, daemon status, schema. Run freely.
  • read_plaintext — reveals decrypted content: clone, env pull, mount. Requires the human's master-password unlock. Never send this plaintext to a cloud model or any external service — decrypted secrets must stay on the machine. Verify content by hash (shasum -a 256), never by printing the bytes.
  • write — mutates the caller's own content or state: sync, env push, env rm, vault create, repair, init, login, device enroll, and so on.
  • share_or_revoke — grants or rotates access for other people, and is effectively irreversible (key rotations, invitations): vault share, vault unshare, device revoke, org invite.

Two lines an agent must never cross on its own

  1. Never run a share_or_revoke verb autonomously. Sharing, unsharing, revoking a device, and inviting to an org all change who can read data — surface the intent and wait for an explicit human go-ahead every time.
  2. Never egress read_plaintext output. Decrypted file or .env bytes must not be sent to a cloud model or any external service. Confirm content by comparing hashes, not by reading it back.

A couple of supporting rules keep secrets off the wire and out of logs: never print, log, or store session tokens, one-time codes, keys, the 12-word recovery phrase, the master password, or raw plaintext; and feed the master password only via the interactive prompt or mani init --password-stdin (first line of stdin) — never an env var or a command argument, both of which leak via ps and shell history.

The manifa skill

For agents, the same contract and consent rules are packaged as the manifa skill in the Manifa repository under skills/manifa/. It covers the --json envelope, the exit-code taxonomy, the scope ladder above, and a worked end-to-end flow (share → clone → verify-by-hash → unshare). Load it when a task involves driving mani, and defer to the live mani schema as the source of truth.

See also