The perma CLI

perma is the command-line control surface for your gateway. Everything the console does, perma can do over the gateway's REST v1 API: manage agents, grants, secrets and policy, read the audit log, and configure connections (including SSH).

It never handles a raw secret in a way an agent could see: values are read from a file, an environment variable, or stdin, and are sealed by the gateway.

Getting perma

perma is built from the same repository as the gateway. If you installed the gateway toolchain it is on your PATH as perma; otherwise build it from source:

cargo build --release -p permaura-cli   # produces target/release/perma

Pointing it at a gateway

Two global flags apply to every command:

Flag	Env	Default
--url	PERMAURA_URL	http://127.0.0.1:8787
--token	PERMAURA_TOKEN	the seeded demo token

On a fresh demo gateway the default token works out of the box. On your gateway, pass your operator token with --token (or set PERMAURA_TOKEN).

perma --url http://127.0.0.1:8787 --token "$PERMAURA_TOKEN" status

A quick tour

perma status                 # gateway health + counts
perma connection list        # configured connections
perma audit --limit 20       # the signed audit log
perma pending                # calls awaiting your approval

See the command reference for everything, or jump straight to connecting via SSH.