Suta CLI

The suta command runs on your computer. Install it with curl -fsSL https://suta.dev/install.sh | bash and choose Suta CLI. Run suta help <command> for examples of any command.

<device> is always a device name or ID. If two devices share a name, use the ID; Suta never guesses.

Global options

These work with every command.

Option	Description
--workspace NAME	Use this workspace for one command. Also SUTA_WORKSPACE.
--json	Print one JSON result. Never prompts or opens a browser.
--no-input	Never prompt or open a browser. Also SUTA_NO_INPUT=true.

suta device list --workspace Lab
suta device list --json
SUTA_NO_INPUT=true suta device inspect kitchen-pi

Sign in and workspaces

suta auth login opens your browser to sign in. The session lasts 30 days and is saved in ~/.config/suta/session.json, readable only by you.

Command	Description
suta auth login	Sign in through your browser.
suta auth status	Show your account, workspace and permissions.
suta auth logout	Sign out and close your remote sessions.
suta workspace list	List your workspaces.
suta workspace use <name>	Set your default workspace.

The CLI acts as you, with your role’s permissions. Anything that runs suta on your computer, including an AI agent, has the same access.

suta auth login
suta auth status
suta workspace list
suta workspace use Workshop

Set up devices

Command	Description
suta flash [disk] [--image FILE]	Flash the Suta image to an SD card.
suta device add	Find a new device nearby and connect it.
suta device network <device>	Repair a device’s network from nearby.

suta flash accepts .img and .img.xz files. Downloaded images are cached in ~/.suta/cache/images/; delete that folder to free space.

These commands are interactive and need a terminal. See Set up a new Pi and Fix a device’s network.

suta flash
suta flash /dev/disk4 --image suta-pi.img.xz
suta device add
suta device network kitchen-pi

Inspect devices

Command	Description
suta device list	List devices and when each was last seen.
suta device inspect <device>	Show identity, network and last reported measurements.
suta device metrics <device> [1h|6h|24h]	Show collected metrics.
suta device service list <device>	List the services the device last reported.

These read what the device last reported. They don’t contact the device.

suta device list
suta device inspect kitchen-pi
suta device metrics kitchen-pi 6h
suta device service list kitchen-pi

Read logs

suta device logs <device> [service] [options]

Option	Default	Description
--since	1h	A duration such as 15m, or an RFC 3339 time.
--until	now	An RFC 3339 time (exclusive).
--search		Only messages that contain this text.
--limit	100	1 to 1000 entries.
--before		The cursor from the previous page.

Logs are kept for 24 hours. Monitoring must be on and collecting the service.

suta device logs kitchen-pi
suta device logs kitchen-pi camera.service --since 15m
suta device logs kitchen-pi --search timeout --limit 500

Remote access

Command	Description
suta device access status <device>	Show whether access is open and until when.
suta device access enable <device> [15m|1h|4h]	Open access. Default 1h.
suta device access disable <device>	Close access and end sessions.

See Remote access.

suta device access enable kitchen-pi
suta device access status kitchen-pi
suta device access disable kitchen-pi

Terminals and commands

Command	Description
suta device ssh <device> [--sudo] [--for 1h]	Open a recorded terminal, 1 minute to 2 hours.
suta device exec <device> [--sudo] -- <program> [args]	Run one program and print its output.
suta device service restart <device> <service>	Restart a service without sudo.

exec options:

Option	Default	Description
--timeout	1m	Stop waiting after up to 5m.
--request-id	new UUID	Reuse after a lost response to avoid running twice.

Output is limited to 1 MiB. The remote exit code (0–255) becomes suta’s exit code. suta exits with 1 if the result is unknown, 2 for invalid arguments and 130 if you cancel.

suta device ssh kitchen-pi
suta device ssh kitchen-pi --sudo --for 15m

suta device exec kitchen-pi -- uname -a
suta device exec kitchen-pi -- sh -c 'uptime; df -h /'
suta device exec kitchen-pi --sudo --timeout 5m -- apt-get update

suta device service restart kitchen-pi camera.service

Monitoring

Command	Description
suta device monitoring status <device>	Show settings and what the device reports.
suta device monitoring enable <device> [services…]	Turn on metrics, plus logs for services.
suta device monitoring disable <device>	Turn off collection, keeping your choices.
suta device monitoring apply <device> <file>	Apply a complete settings file.

suta device monitoring enable kitchen-pi camera.service
suta device monitoring apply kitchen-pi settings.json

settings.json

{
  "enabled": true,
  "services": ["camera.service"],
  "process_metrics": false,
  "sample_interval_seconds": 30
}

Activity

suta workspace activity [device] [options]

Option	Default	Description
--since		A duration such as 1d, or an RFC 3339 time.
--limit	20	1 to 200 entries.
--before		The cursor from the previous page.
--request		Find one operation by its request ID.

suta workspace activity
suta workspace activity kitchen-pi --since 1d
suta workspace activity --request 3f0c…

Rollouts

Command	Description
suta rollout start [options]	Update the agent on matching devices in stages.
suta rollout list	List recent rollouts.
suta rollout show [rollout]	Show progress, stages and every device.
suta rollout wait [rollout]	Wait until the rollout finishes or pauses.
suta rollout pause|resume|retry|cancel [rollout]	Control a rollout.

Without an ID, these commands use the current rollout, or the most recent one.

start options:

Option	Default	Description
--tag	all devices	Only devices with this tag. Repeat to require several.
--canary	1	Devices to update first, 0 to 20.
--batch	5	Devices to update at a time after the canary, 1 to 500.
--max-failures	0	Failures to allow before pausing, 0 to 100.
--dry-run		Show which devices would update, without starting.
--wait		Wait until the rollout finishes or pauses.

wait and start --wait exit with 1 if the rollout pauses, is cancelled or any device fails. See Update the agent.

suta rollout start --tag site-london --dry-run
suta rollout start --tag site-london --canary 1 --batch 5 --wait
suta rollout show
suta rollout retry

Alerts

Command	Description
suta alert list [--all] [--kind K] [--device D]	List open alerts, or every alert with --all.
suta alert conditions [options]	Show alert conditions, or change them.
suta alert webhook list	List webhooks and their recent deliveries.
suta alert webhook add <name> <url>	Add a webhook and print its signing secret.
suta alert webhook test|pause|resume|rotate|remove <webhook>	Manage a webhook.

conditions takes --offline MINUTES, --memory PERCENT, --storage PERCENT and --temperature CELSIUS, each also accepting off, and --update-failed on|off. webhook add takes --on opened,resolved and --kind to limit which alerts it receives. Changing conditions and webhooks needs a workspace admin. See Alerts.

suta alert list
suta alert list --all --kind storage
suta alert conditions --storage 85 --temperature off
suta alert webhook add Ops https://hooks.slack.com/services/…
suta alert webhook test Ops

API tokens

Command	Description
suta workspace token list	List API tokens.
suta workspace token create <name> --role <role>	Create a token and print it once.
suta workspace token revoke <token>	Revoke a token immediately.

--expires is 30d, 90d (default), 365d or never. Managing tokens needs a workspace admin. See API tokens.

suta workspace token create CI --role Operator --expires 30d
suta workspace token revoke CI

Maintenance

Command	Description
suta update	Update the CLI. Keeps you signed in.
suta completions <bash|zsh|fish>	Print a shell completion script.

suta update updates the CLI on your computer, not the agent on devices.

suta update
suta completions zsh > "${fpath[1]}/_suta"

JSON output

With --json, suta prints exactly one JSON object to standard output. Progress and messages go to standard error.

A failed remote command also includes data, with the state, exit code and any output.

Human-readable output escapes control characters from devices. JSON output keeps the original text.

Success

{ "ok": true, "data": { "…": "…" } }

Failure

{
  "ok": false,
  "error": { "code": "permission_denied", "message": "…" }
}

Environment variables

SUTA_TOKEN uses an API token instead of your login, SUTA_WORKSPACE sets a default workspace, SUTA_NO_INPUT=true disables prompts, and SUTA_SESSION_FILE stores your session somewhere else.