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_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.

There is no signing key to manage The CLI sends your files; the control plane packs and signs them when a release is deployed. Nothing to generate, store in a secret store, or lose. See Key management for what the signature establishes.

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.
`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 and check the exit code rather than parsing human output.

There is no public installer to curl on a runner: the binary is downloaded from the portal by a person, then staged into your runner image or kept as a build artefact. It is one static file with no dependencies, so staging it is a copy.

.github/workflows/release.yml

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

      - name: Install arda
        run: install -m 755 ci/arda-linux-amd64 /usr/local/bin/arda

      - name: Push and stage
        env:
          ARDA_TOKEN:    ${{ secrets.ARDA_TOKEN }}
        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.

PreviousQuickstart NextPackage format

arda CLIreference.