Command reference

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

Setup and status

perma init              # scaffold ~/.permaura config
perma serve             # run a local gateway (in-memory demo)
perma status            # gateway health, versions and counts

Agents

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

Grants

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

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

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

Approvals and audit

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

Policy

Evaluate a decision locally, without touching a gateway:

perma 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):

perma connection list

perma 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