The permaura CLI

permaura is the command-line control surface for your gateway. Everything the console does, permaura 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 permaura

permaura is the gateway. There is one binary: permaura start runs a gateway, and every other command drives one. So if you have a gateway, you already have the CLI.

# Installed with npm: `permaura` is already on your PATH.
permaura status

# You installed with the one-liner: it is on disk already.
~/.permaura/bin/permaura status

# Nothing installed, and you'd rather keep it that way:
npx -y permaura status

# From source:
cargo build --release -p permaura-gateway   # produces target/release/permaura

npm i -g permaura is the shortest route to having permaura on your PATH. If you installed with the one-liner instead, add ~/.permaura/bin to your PATH to type permaura on its own. Running permaura with no arguments prints the help and starts nothing — starting a gateway is always permaura start.

Pointing it at a gateway

Two global flags apply to every command:

Flag	Env	Default
--url	PERMAURA_URL	http://127.0.0.1:7376
--token	PERMAURA_TOKEN	the operator token at ~/.permaura/operator.token

Against a gateway on this machine there is usually nothing to pass: the gateway wrote its own operator token to ~/.permaura/operator.token when it first started, and the CLI reads it. For a gateway somewhere else, pass both.

There is deliberately no fallback token. A tool that quietly presented a published constant would be an authentication bypass against a seeded gateway, so when no token can be found the CLI sends none and the gateway answers 401.

permaura --url http://127.0.0.1:7376 --token "$PERMAURA_TOKEN" status

Where the console thinks this gateway is

--url is where you are calling from. Separately, permaura.com holds one address per gateway, and that is what the web console dials when the gateway is on the same machine as the browser. Enrolment sets it once, from whatever the installer advertised.

Two situations leave it wrong, and one command fixes both:

permaura advertise http://127.0.0.1:7377

• You moved the gateway to another port. The desktop app does this for you under Settings, but a --port reinstall or a PERMAURA_ADDR change does not.
• The gateway is in a VM or container. The installer runs inside the guest and advertises what it can see there, but the browser is on the host, so the address that works is the host side of the port forward. PERMAURA_ADVERTISE_ADDR sets the same thing at install time.

The address has to be a loopback one, because this is only about a gateway the browser reaches directly. Anything further away goes through remote access.

A quick tour

permaura start                  # run the gateway (Ctrl-C, or `permaura stop`, to end it)
permaura status                 # gateway health + counts
permaura connection list        # configured connections
permaura audit --limit 20       # the signed audit log
permaura pending                # calls awaiting your approval
permaura upgrade                # replace this binary with the latest published release
permaura advertise <url>        # tell permaura.com where the console should call this gateway

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