Admiral CLI & Remote SSH
The admrl command-line tool signs in with your Admiral account, manages devices, fleets, and configurations as documents, diagnoses devices, drives rollouts, and opens SSH sessions to devices over the Admiral Mesh. Devices need no inbound ports, public IP, or VPN, and no shared credentials ever live on your machine.
Installing
The CLI is a single static binary with no runtime dependencies. There is one build per platform:
| Platform | File |
|---|---|
| macOS, Apple silicon | admrl-darwin-arm64 |
| macOS, Intel | admrl-darwin-amd64 |
| Linux, x86-64 | admrl-linux-amd64 |
| Linux, ARM64 | admrl-linux-arm64 |
| Windows, x86-64 | admrl-windows-amd64.exe |
Rename the file to admrl (admrl.exe on Windows), make it executable, and put it on your PATH:
chmod +x admrl-darwin-arm64
sudo mv admrl-darwin-arm64 /usr/local/bin/admrl
admrl version
To update, replace the binary with a newer build. Your sign-in is kept in your user configuration directory and survives updates.
Your sign-in is stored in ~/Library/Application Support/admrl on macOS, ~/.config/admrl on Linux, and %AppData%\admrl on Windows. Set ADMRL_CONFIG_DIR to use another location, for example one directory per organisation or a throwaway directory in CI.
Signing In
admrl login
The CLI prints a link and a short code (for example BKDF-QRTZ). Open the link while signed in to the dashboard (https://app.admrl.co/cli/activate), check that the code matches your terminal, and review the request: the computer name, the IP address it came from, and when it was made. Click Approve (or Deny if you did not run admrl login).
- Codes expire after 10 minutes.
- A CLI sign-in lasts 24 hours. Run
admrl loginagain the next day. - The token is stored only on your machine, readable only by your user. Admiral keeps only a hash of it.
| Command | Purpose |
|---|---|
admrl login [--api URL] | Sign in. Defaults to https://api.admrl.co. |
admrl whoami | Show the signed-in user and when the sign-in expires. |
admrl logout | Revoke the token and delete it locally. |
admrl ssh-config | Print an ~/.ssh/config block for Admiral devices. |
admrl ssh-proxy [-v] [--relay|--direct] [--api URL] <device-id> | SSH ProxyCommand (used by the config block). <device-id> may end in .admrl. See Troubleshooting the connection. |
admrl use-org [<org-id>] | Show or set the organisation used by the document, diagnostics, and rollout commands below. --org <id> or ADMRL_ORG override it per command. |
admrl version | Print the CLI version and build. admrl --version does the same. |
admrl help | Print the command summary. admrl -h and admrl --help do the same. |
Flags and Environment
These flags work on every document, diagnostics, and rollout command:
| Flag | Meaning |
|---|---|
--org <id> | Organisation to use for this command. Overrides ADMRL_ORG and admrl use-org. |
--api <url> | API to talk to. It must be the one you signed in to. |
| Variable | Meaning |
|---|---|
ADMRL_API | API URL (default https://api.admrl.co). --api overrides it. |
ADMRL_ORG | Organisation for document, diagnostics, and rollout commands. |
ADMRL_CONFIG_DIR | Where the sign-in is stored. |
ADMRL_DEBUG | 1 or true logs transport details to stderr, the same as ssh-proxy -v. |
EDITOR, VISUAL | Editor opened by admrl edit. |
NO_COLOR | Disable coloured output. |
Devices, Fleets & Configurations as Documents
Every device, fleet, and configuration is a document you can read, edit, diff, and apply. Arguments accept a name or an ID; if a name is ambiguous the CLI lists the matching IDs.
| Command | Purpose |
|---|---|
admrl get devices|fleets|configurations [-l k=v] [-o wide|yaml|json] | List, optionally filtered by label (repeatable -l). |
admrl get device|fleet|configuration <id|name> [-o yaml|json] | Print one document (YAML by default). |
admrl edit device|fleet|configuration <id|name> [--yes] | Open the document in $EDITOR, show the server's render diff, and confirm before writing. status is read-only and ignored. |
admrl apply -f <file|-> [--dry-run] | Update one or more existing documents from a file (or stdin). --dry-run validates and shows the render diff without writing. |
admrl diff -f <file|-> | Show what applying the file would change on the devices. |
admrl move device <id|name> --fleet <id|name> | Move a device to another fleet. |
admrl override device <id|name> --set k=v... [--unset k] [--expires 2h] | Change the device's workload override. Keys: env.NAME=value, desiredState=stopped, image=..., or any override path. --expires drops the override automatically. |
admrl override device <id|name> --clear | Remove the whole override. |
admrl watch device <id|name> | Stream condition changes, workload changes, and progress (image_pull 41% 12 MB/s eta 20s layer 3/5) until Ctrl-C. |
admrl get device amr-dock-07 -o yaml > amr-dock-07.yaml
# edit the file, then:
admrl diff -f amr-dock-07.yaml
admrl apply -f amr-dock-07.yaml
apply and edit only write if the document has not changed since you fetched it. If it has, they stop with exit code 3: fetch it again and re-apply your change.
Diagnostics
| Command | Purpose |
|---|---|
admrl diagnose device <id|name> | Verdict and issues from the device's last reports. Works offline. |
admrl state device <id|name> [--live] [-o yaml|json] | The device's reported state. --live asks the device now (online devices only). |
admrl probe device <id|name> [--section s] [--timeout 20s] | Run the live probe on the device; --section (repeatable) limits it to network, time, storage, and so on. --timeout is the device-side budget (default 20 seconds, maximum 60). |
A live state read and a live probe share one limit of one request per 5 seconds per device. Repeating either sooner fails with "the device is busy with another command, try again": wait a few seconds and run it again.
See Device State & Diagnostics.
Rollouts
| Command | Purpose |
|---|---|
admrl rollout create -f fleet.yaml [--canary 1] [--max-in-flight 50] [--max-unavailable 2] [--failure-threshold 0.1] [--progress-deadline 30m] [--name n] [--description text] [--dry-run] [--watch] | Roll the configuration version pinned in a Fleet document (spec.configuration with an explicit version) out to that fleet. --dry-run shows the per-device changes and creates nothing. |
admrl rollout status <id|name> [--watch|-w] [-o yaml|json] | Status and counts (admrl rollout get is the same command); --watch prints one line per device phase change until the rollout finishes. |
admrl rollout pause|resume <id|name> | Pause or resume admitting devices. |
admrl rollout cancel|rollback <id|name> [--yes] | End the rollout, or send admitted devices back to their previous version. Asks for confirmation unless --yes. |
See Rollouts.
Exit Codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Error (network, permission, validation, device offline). |
2 | Usage error (bad flags or arguments). |
3 | Conflict: the document changed since you fetched it, or the rollout cannot take that action in its current state. |
SSH to a Device
Add the Admiral block to your SSH config once:
admrl ssh-config >> ~/.ssh/config
Then connect by device ID:
ssh root@<device-id>.admrl
The block matches every host ending in .admrl and uses admrl ssh-proxy as its ProxyCommand. It also keeps device host keys in ~/.ssh/known_hosts_admrl, apart from your other hosts, and sends a keep-alive every 30 seconds.
Or without the config block:
ssh -o ProxyCommand='admrl ssh-proxy %h' root@<device-id>
Because the CLI is only the transport, everything that runs over SSH works the same way, including file transfer and port forwarding:
scp ./patch.tar.gz root@<device-id>.admrl:/tmp/
sftp root@<device-id>.admrl
ssh -L 8080:localhost:8080 root@<device-id>.admrl
The CLI requests a one-hour session credential for that one device. Where the network allows, the session runs over a direct peer-to-peer path; otherwise it is relayed through Admiral Cloud. Sessions are wrapped in a hybrid post-quantum (ML-KEM-768 + X25519) encrypted tunnel, with SSH running end to end inside it.
Admiral decides who may open a connection to the device. The device's own SSH server still authenticates you with the keys it trusts: the SSH keys you register in your account (see below).
Troubleshooting the connection
admrl ssh-proxy accepts these flags. Pass them in the ProxyCommand line, or set ADMRL_DEBUG=1 for -v.
| Flag | Meaning |
|---|---|
-v | Log transport details to stderr: the device name, whether a direct path was found or the session is relayed, and when a direct path is lost. |
--direct | Use the peer-to-peer path only. Fails instead of relaying. Use it to test whether a network allows direct connections. |
--relay | Skip the direct path and relay through the Mesh. Use it when a firewall makes the direct attempt slow. |
--api <url> | API to use. It must match the one you signed in to. |
--direct and --relay cannot be combined. If the CLI reports that you are signed out, run admrl login again.
Your SSH Keys
Register your own public key once and use it on every device you can open a shell to. You get full root access with it; Admiral adds no restrictions to your key.
- Open Account > SSH keys and choose Add SSH key.
- Paste the contents of your public key file (for example
~/.ssh/id_ed25519.pub). Ed25519, ECDSA and RSA (2048-bit or larger) are supported. Never paste a private key. - Connect with
ssh root@<device-id>.admrl.
Online devices receive a new or removed key within seconds. A device that was offline catches up within 15 minutes of reconnecting. A key is trusted only on devices where its owner holds the Remote shell permission, so removing someone's access also removes their key from those devices: immediately when they are deactivated or removed from the organisation, otherwise at the device's next sync (every 15 minutes).
Each login is recorded in the device's logs with the key's SHA-256 fingerprint, which matches the fingerprint shown next to the key in your account.
Admiral support access
Admiral support staff can only log in to your devices while Support access is enabled for your organisation in Settings > Support access. When you disable it, Admiral's support keys are removed from every device in the organisation; your own keys are unaffected. A device that has not been claimed into an organisation yet accepts the Admiral support keys so that provisioning can be assisted.
Who Can Open a Shell
Opening an SSH session requires the Remote shell permission on the device:
- Device admins and fleet admins have it automatically.
- Members and editors do not, and need an explicit grant through an IAM policy.
Every session is recorded in the audit log.
Revocation
Live sessions and CLI sign-ins end automatically when:
- the user is deactivated or deleted (their CLI sign-ins are also revoked);
- the user is removed from the organisation (sessions on that organisation's devices end);
- the device is deleted, unpaired, or wiped.
A relayed session also ends when its one-hour credential expires or the connection drops; reconnect to start a new one.