Command reference

Every command accepts the global --url and --token flags (see the overview).

Setup and status

permaura init              # scaffold ~/.permaura config
permaura start             # run the gateway (--addr, --pair, --mock, --demo)
permaura status            # gateway health, versions and counts
permaura stop              # ask it to drain in-flight calls and exit
permaura upgrade           # replace this binary with the latest published release

permaura on its own prints the help and starts nothing: start is the only command that serves.

start --demo, and a start on an in-memory store (PERMAURA_STORE_PATH=:memory:), run a throwaway gateway beside your real install. From gateway 1.3.51 a throwaway takes nothing from config.toml, leaves the install's operator token alone, and starts no tunnel connector, relay or pairing of its own. From gateway 1.3.56, a demo binds only to loopback and defaults to 127.0.0.1:7399, ignoring PERMAURA_ADDR unless you supply --addr explicitly. For example, permaura start --demo --addr 127.0.0.1:7399. A non-demo in-memory gateway still uses its configured address, so give it its own: a tunnel or proxy you run yourself forwards to whatever listens on the port it points at. It refuses --pair, and ignores a PERMAURA_PAIR_CODE left in the environment.

Remote access

permaura remote enable [name]   # ask Permaura for a managed tunnel and write its settings (--yes to move an address in use)
permaura remote status          # the public address, and whether the tunnel's credentials are stored
permaura remote disable         # clear the address settings and the tunnel files stored on this machine

All three act on this machine's gateway. enable needs it paired with your Permaura account, and from gateway 1.3.51 it refuses, before writing anything, an answer whose sign-in issuer or signing-key address is not on the account API's own origin; status and disable read and clear only what is stored on this machine. Restart the gateway after enable or disable; permaura start runs the tunnel itself, and if the tunnel stops, nothing starts it again until the gateway restarts. From gateway 1.3.48, enable stores the tunnel's credentials in tunnel-credentials.json in the gateway's data directory, and start writes the connector's configuration beside it as cloudflared.yml. Both are owner-only files, and the configuration names one destination for your permaura.app hostname: the port the gateway is listening on. disable removes both. If the gateway stopped the tunnel because its connector was running something other than what this machine wrote, or carrying private-network traffic, it records why in tunnel.stopped, status shows it, and the tunnel stays stopped across restarts until enable or disable clears it. A tunnel.token an older gateway stored is a run token for a remotely managed tunnel, which this version no longer runs; status says so, and enable replaces it. disable does not tell permaura.com, which keeps the tunnel and the name reserved, so also press Pause (or delete it) on the gateway's card under Settings → Gateway in the console. See Remote access.

Agents

permaura agent add "Codex CLI"      # register an agent; prints its id

Grants

Bind allow/deny rules for a connection (resource) to an agent:

permaura grant --agent codex-cli --resource db1 \
  --allow uptime --allow sftp.get \
  --deny sftp.put \
  --max-calls 100

Secrets (vault)

Values are read from an environment variable or stdin, never an argument, and are never echoed back:

permaura vault add sec_api --env-var MY_API_KEY
permaura vault list                 # ids only, never values

Approvals and audit

permaura pending                    # calls held for a human decision
permaura approve appr_abc           # run a held call, return the redacted result
permaura deny appr_abc              # reject a held call; nothing runs
permaura audit --limit 50           # the hash-chained, signed audit log

Policy

Evaluate a decision locally, without touching a gateway:

permaura policy test --capability transactions.refund --action refund \
  --resource braintree_prod --risk critical

Connections

List configured connections, or add an SSH host (see Connecting via SSH for the full guide):

permaura connection list

permaura connection add-ssh db1 \
  --host db1.example.com --user deploy \
  --host-key-sha256 "SHA256:9Ije…" \
  --key-file ~/.ssh/db1_ed25519 \
  --sftp-root /var/data \
  --exec 'uptime:uptime' \
  --exec 'restart:systemctl,restart,{service}' --require-approval \
  --agent codex-cli

connection add-ssh flags

Flag	Meaning
<id>	connection id; capabilities are namespaced under it (db1.uptime)
--host, --port, --user	the SSH target, pinned server-side (default port 22)
--host-key-sha256 <fp>	expected host-key fingerprint; required unless --insecure
--insecure	skip host-key verification (local/dev only)
--key-file <path>	unencrypted private key to seal (public-key auth)
--password-env <VAR>	use password auth, reading the password from that env var
--sftp-root <path>	expose path-scoped sftp.get/put/list under this root
--exec 'action:prog,arg,{ph}'	an allow-listed exec command (repeatable); {ph} args become placeholders
--agent <id>	also allow the declared actions and grant them to this agent
--require-approval	mark the exec commands as needing human approval

Exit status

Every command that writes to a gateway reports what the gateway did, not just that it answered. From gateway 1.3.46 the process exit status tells scripts the same thing:

Exit status	Meaning
0	done: every step was applied and the output names what was created. A vault import also exits 0 when the gateway refused some items; it prints each one it refused
1	failed, refused or unconfirmed: a step answered with an error, or its answer did not name the created item, or the connection failed before an answer came back. The message carries the gateway's reason where there is one. The failed step is not applied, but earlier steps of a multi-step command may already be (for example grant creates its policy before the grant, and connection add-ssh creates the connection before sealing the credential), and an unconfirmed step may or may not have landed
2	usage error found while reading the command line: an unknown flag, or a missing or malformed argument. A value the command checks for itself afterwards, such as an --exec or --expires it cannot read, exits 1
3	held for a device signature: a step was accepted but a paired device must approve it first. The output names the approval id, and permaura pending lists it. That step is not applied until it is approved; the command's other steps may already be applied or held, so follow each printed status

An exit of 1 or 3 means the command is incomplete, not that nothing happened. Before retrying, read the ids and statuses the command printed and check them where they are visible: the console's Agents, Grants, Vault and Connections pages, permaura status, permaura pending for a held step, permaura vault list for secrets and permaura connection list for connections. Re-running a command whose earlier steps already applied can create a second policy or connection. The npm launcher forwards the binary's exit status unchanged.