arda CLI
reference.

A git-style command line for device fleets. Non-interactive by default, authenticates from the environment, exits non-zero on failure, and speaks --json when you'd rather parse than read.

Preview — command names and flags may change before 1.0

Global flags

Accepted by every command.

Flag	Meaning
`--fleet <name>`	Target a fleet other than the one the workspace is linked to.
`--json`	Machine-readable output on stdout. Diagnostics go to stderr.
`--quiet`, `-q`	Suppress progress output; errors still print.
`--verbose`, `-v`	Full request and timing detail. Repeat for more.
`--yes`, `-y`	Skip confirmation prompts. Implied when stdout is not a TTY.
`--timeout <dur>`	Overall command timeout, e.g. `30s`, `5m`.
`--config <path>`	Use an alternative `arda.json`.

Environment

Variable	Purpose
`ARDA_TOKEN`	API token. Replaces `arda login` on CI runners. Scoped per fleet, revocable.
`ARDA_PACK_KEY`	Private signing key for packages, PEM or base64. Never uploaded.
`ARDA_FLEET`	Default fleet when no workspace link exists.
`ARDA_ENDPOINT`	Control plane URL. For self-hosted deployments.
`NO_COLOR`	Disable ANSI colour, per the `no-color` convention.

Keep the pack key out of the repo It signs code that runs on your customers' hardware. Put it in your CI secret store. The control plane never holds it and cannot sign on your behalf — which also means it cannot recover it for you.

Project

arda login [--token <t>]

Authenticate this machine. Opens a browser by default; pass --token for headless use. Credentials are stored in ~/.config/arda/.

arda logout

arda init [name] [--template <t>]

Scaffold a project directory with arda.json and a minimal application. Templates: blank (default), kiosk, till, signage.

arda link [fleet] [--group <g>] [--channel <c>]

Bind the working directory to a fleet. Writes the link to arda.json, so a colleague who clones the repository is already pointed at the right place.

arda build [--out <path>] [--no-encrypt]

Run the manifest's build command, bundle the output, sign and encrypt it. Produces app.arda without contacting the control plane — useful for air-gapped signing and for CI jobs that upload separately. --no-encrypt is for local inspection only and produces a package no device will accept.

arda version

Releases

arda push [-m <message>] [--channel <c>] [--tag <t>]

Build as above, then upload the package as a new immutable release. Prints the release ID and SHA-256. If the identical content has already been pushed, the existing release is reused rather than duplicated.

shell

$ arda push -m "new order screen" --channel beta
  building    dist/ → app.arda
  signing     ed25519 ✓
  encrypting  aes-256-gcm ✓
  uploading   1.84 MB · sha256 4f9c…a10e
✓ release r-241 → channel beta

arda releases [--limit <n>] [--channel <c>]

List releases with ID, message, size, hash, channel and creation time.

arda promote <release> --channel <c>

Move an existing release to another channel — the normal beta → stable path. No rebuild, so the exact bytes you tested are the bytes that ship.

arda tag <release> <name>

Deployment

arda deploy [release] [target] [options]

Point devices at a release. With no release, deploys the newest in the linked channel. With no target, deploys to the whole linked fleet.

Flag	Meaning
`--device <id>`	One device. Repeatable.
`--group <g>`	All devices in a group. Repeatable.
`--channel <c>`	All devices subscribed to a channel.
`--wave <n\|%>`	Deploy in waves of n devices or a percentage of the target.
`--pause <dur>`	Hold between waves, e.g. `10m`. Aborts if errors appear.
`--staged`	Shorthand for `--wave 25% --pause 5m`.
`--max-errors <n>`	Abort the rollout after n device failures. Default 1.
`--watch`	Stream progress until the rollout finishes.

arda rollback [target] [--to <release>]

Send the previous release back down the same path. Devices retain the previous package, so this is a message rather than a re-download where possible.

arda pin <device> <release> · arda unpin <device>

Hold specific devices on a specific release. Pinned devices are skipped by rollouts and reported separately, so a delicate site can sit still while everything else moves.

arda cancel [rollout]

Stop an in-flight rollout. Devices mid-download finish and stage but do not swap; devices not yet instructed are left alone.

Fleet

arda devices [--group <g>] [--state <s>]

List devices with ID, group, current release, state and last-seen. --state filters on online, offline, stale or pending.

arda status

Fleet summary: device counts by state, release distribution and any rollout in progress.

arda claim <code> [--group <g>] [--name <n>]

arda group <list|create|add|remove> […]

arda env <get|set|unset|list> [key[=value]] [target]

Read and write the configuration delivered to devices as arda.app.config(). Applied without a new release; running applications receive a config event.

shell

$ arda env set TAX_RATE=0.20 --group uk
$ arda env set SITE_NAME="Camden Road" --device af-0c41d9
$ arda env list --device af-0c41d9

arda rename <device> <name>

Support

arda logs <device> [--follow] [--level <l>] [--since <dur>]

Stream the device's application console with levels and timestamps.

arda console <device>

Attach an interactive JavaScript console to the running page. Expressions are evaluated in the live application — powerful, and correspondingly easy to break a live device with.

arda screenshot <device> [-o <file>] [--format <f>] [--quality <n>]

Capture what the device is displaying. Formats: png (default), jpeg, webp, avif.

arda watch <device> [--interval <ms>]

Stream frames as the screen changes. Minimum interval 500 ms.

arda shell <device>

Open an SSH session to the device over an operator-initiated reverse tunnel. Requires shell access to be enabled on the fleet; the session is short-lived and logged.

arda exec <device> -- <command>

Run a single shell command and return its output and exit code. Subject to a 30-second timeout.

arda info <device>

The device's hardware and OS snapshot: distribution, kernel, architecture, CPU, memory, disk, GPU, network interfaces and attached USB devices.

arda restart <device> [--reboot]

Restart the application, or the whole machine with --reboot.

Exit codes

Code	Meaning
`0`	Success.
`1`	General failure.
`2`	Usage error — bad flag or missing argument.
`3`	Not authenticated, or the token lacks the required scope.
`4`	Build failed. The build command's own output is passed through.
`5`	Signing or encryption failed — usually a missing or malformed pack key.
`6`	Rollout aborted after reaching `--max-errors`.
`7`	Target device is offline and the command requires it to be present.
`8`	Timed out.

CI usage

Every command is safe to run unattended. Authenticate with ARDA_TOKEN, sign with ARDA_PACK_KEY, and check the exit code rather than parsing human output.

.github/workflows/release.yml

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install arda
        run: curl -fsSL https://ardaform.net/install.sh | sh

      - name: Push and stage
        env:
          ARDA_TOKEN:    ${{ secrets.ARDA_TOKEN }}
          ARDA_PACK_KEY: ${{ secrets.ARDA_PACK_KEY }}
        run: |
          arda push -m "$GITHUB_SHA" --channel beta
          arda deploy --channel beta --staged --watch

Promote, don't rebuild When beta looks healthy, run arda promote <release> --channel stable. Rebuilding for production ships bytes nobody tested.

PreviousJavaScript API reference NextPackage format

arda CLIreference.