Skip to content

CLI Commands

Practical arcane-cli invocations for everyday tasks.

Find the arcane-cli commands you’ll use most, grouped by task. First set your server URL and sign in (see CLI Configuration). Run arcane-cli <command> --help for all flags, or arcane-cli --help for the full command tree.

Log in interactively with the device-code flow:

Terminal window
arcane-cli auth login

Check who you’re signed in as, or sign out:

Terminal window
arcane-cli auth me
Terminal window
arcane-cli auth logout

For CI, use an API key or a federated credential instead. See Federated Credentials.

Commands cover every agent by default. Use --agent for only one:

Terminal window
arcane-cli containers list --agent 2

Changes without --agent ask for confirmation before they run on all agents. See Work across agents.

List agents and check one is reachable:

Terminal window
arcane-cli agents list
Terminal window
arcane-cli agents test 2

Close an agent’s tunnel so it reconnects. Needs environments:restart:

Terminal window
arcane-cli agents tunnel restart 2

Add an agent. The CLI prints a single-use enrollment token once, then the docker run and Compose commands to start the agent on the remote host:

Terminal window
arcane-cli agents create --name production
Terminal window
arcane-cli containers list
Terminal window
arcane-cli containers get my-container
Terminal window
arcane-cli containers restart my-container

List containers with a newer image available:

Terminal window
arcane-cli containers updates

Pull the newer image and recreate the container:

Terminal window
arcane-cli containers update my-container
Terminal window
arcane-cli projects list
Terminal window
arcane-cli projects up my-project
Terminal window
arcane-cli projects down my-project

Pull the latest images and restart:

Terminal window
arcane-cli projects redeploy my-project

Remove a project and its resources:

Terminal window
arcane-cli projects destroy my-project

Add a global variable for every agent, or pass --agent <id> once per agent to limit it. Without --inject it’s only used for ${VAR} substitution; see Variables:

Terminal window
arcane-cli variables create --key DOMAIN --value example.com

Push variables to every agent now, or show the last sync result with --status:

Terminal window
arcane-cli variables sync
Terminal window
arcane-cli images list
Terminal window
arcane-cli images pull nginx:latest

Reclaim space:

Terminal window
arcane-cli images prune
Terminal window
arcane-cli volumes sizes

Find out what’s using a volume before you remove it:

Terminal window
arcane-cli volumes usage my-volume
Terminal window
arcane-cli gitops list
Terminal window
arcane-cli gitops status my-sync
Terminal window
arcane-cli gitops sync my-sync

Create a sync. --mode is deploy (pull, the default), backup (push), or bidirectional (pull and push). backup and bidirectional take --project, --backup-directory, and repeatable --backup-path.

Terminal window
arcane-cli gitops create --name my-app --mode bidirectional --repo-id <repo-id> --branch main --project my-app --backup-directory projects/my-app

For a sync that pushes to Git, preview the next push, list its revisions, or resolve a conflict. --strategy is use_arcane (default) or use_repository, which only a bidirectional sync accepts.

Terminal window
arcane-cli gitops preview my-app
Terminal window
arcane-cli gitops history my-app --limit 20
Terminal window
arcane-cli gitops resolve my-app --strategy use_repository

Add a Git repository. --provider (github, gitlab, gitea, or bitbucket) sets the link format for files and commits; leave it out to detect it from the URL. repos update takes the same flag.

Terminal window
arcane-cli repos create --name my-repo --url https://git.example.com/me/stacks.git --provider gitea

Free up space on every agent, or pass --agent for one:

Terminal window
arcane-cli system prune

Check whether an Arcane upgrade is available, and apply it:

Terminal window
arcane-cli system upgrade --check
Terminal window
arcane-cli system upgrade

Turn a docker run command into Compose:

Terminal window
arcane-cli system convert "docker run -d -p 8080:80 nginx"

Get a summary or the full findings list, scan an image now, or show one image’s findings:

Terminal window
arcane-cli images vulnerabilities summary
Terminal window
arcane-cli images vulnerabilities list
Terminal window
arcane-cli images vulnerabilities scan nginx:latest
Terminal window
arcane-cli images vulnerabilities image nginx:latest

Silence a CVE you’ve reviewed (and list or undo ignores with ignored / unignore):

Terminal window
arcane-cli images vulnerabilities ignore CVE-2026-1234

Set a user’s role assignments. Add :<agent-id> to scope one to an agent:

Terminal window
arcane-cli admin roles assign <user-id> --role role_deployer:<agent-id>

List a user’s assignments:

Terminal window
arcane-cli admin roles assignments <user-id>

Map an OIDC claim value to a role:

Terminal window
arcane-cli admin oidc create --claim docker-admins --role role_admin

Read the Event Log:

Terminal window
arcane-cli admin events list
  • Custom roles: admin roles list, get, create, update, delete, permissions.
  • Assignments: admin roles assign and assignments.
  • See Roles & Permissions.

Manage Arcane system backups from the terminal:

Terminal window
arcane-cli admin backups list
Terminal window
arcane-cli admin backups create
Terminal window
arcane-cli admin backups restore <backup-id>

There are also subcommands for retention policies (policies), the recovery key (recovery), uploading a local backup to S3 (upload), and finding S3 restore points not in the database (discover).

These commands manage the manager’s backups. Remote agent backups are managed under System → Backups.

These commands work on Podman agents; see Podman Overview for host requirements. Check what the host supports first:

Terminal window
arcane-cli podman status

Pods take the same flags as podman pod create:

Terminal window
arcane-cli podman pods list
Terminal window
arcane-cli podman pods create --name web -p 8080:80 --memory 512m
Terminal window
arcane-cli podman pods stop web --timeout 30
Terminal window
arcane-cli podman pods delete web --force

Install a Quadlet with any files it needs, then start its unit:

Terminal window
arcane-cli podman quadlets install web.kube --extra-file web.yaml
Terminal window
arcane-cli podman quadlets start web.kube

Play, tear down, or generate Kubernetes YAML:

Terminal window
arcane-cli podman kube play web.yaml --replace
Terminal window
arcane-cli podman kube down web.yaml
Terminal window
arcane-cli podman kube generate web --type deployment --service

Create or replace a secret. Without --file, the CLI prompts for the value, or reads one line from stdin:

Terminal window
arcane-cli podman secrets create db-password --file ./db-password.txt
Terminal window
arcane-cli podman secrets update db-password

Run Podman auto-update. --dry-run needs Podman 6.2 or later:

Terminal window
arcane-cli podman autoupdate --dry-run
Terminal window
arcane-cli activities list
Terminal window
arcane-cli activities get <activity-id>

Manage webhooks, or fire one by its token:

Terminal window
arcane-cli webhooks list
Terminal window
arcane-cli webhooks trigger <token>

Inspect the automatic updater, trigger a run, and view history:

Terminal window
arcane-cli updater status
Terminal window
arcane-cli updater run
Terminal window
arcane-cli updater history

History shows one row per resource: resource, type, status, whether the update was applied, and start time. --limit (-n) sets how many entries return; the default is 50.

Terminal window
arcane-cli self-update run

Switch between the stable and next release channels:

Terminal window
arcane-cli self-update channel next

self-update checks the release signature before it trusts any checksum. Every release signs its checksum file with the Arcane cosign key and records it in Sigstore’s public transparency log. The CLI downloads the checksum file and its .sigstore.json bundle and confirms the file was signed with the Arcane key, is in the transparency log, and is unchanged. Only then does it check the binary against that checksum. The key is built in, so you don’t need cosign installed.

If verification fails, the update stops and your binary is unchanged; there’s no fallback to an unverified update. Verification also runs with --dry-run and --json, and the JSON output reports signatureVerified and bundleUrl.

The first update downloads Sigstore’s trust data from tuf-repo-cdn.sigstore.dev. It’s cached in arcane-cli/sigstore under your user cache directory (~/.cache on Linux, ~/Library/Caches on macOS). Later updates use the cache, even offline, until the trust data expires; then the CLI must reach tuf-repo-cdn.sigstore.dev again.

Releases before v1.18.0 are unsigned, so self-update can’t install them. A signature proves Arcane published a release. It does not stop you from installing an older signed release, for example with --version.

Diagnose connectivity and configuration problems, install shell completion, or generate secrets and certificates for a new install:

Terminal window
arcane-cli doctor
Terminal window
arcane-cli completion zsh
Terminal window
arcane-cli generate secret

Every command accepts --output json (or --json), so you can pair it with jq:

Terminal window
arcane-cli containers list --json | jq -r ".data[].name"

In JSON mode, stdout carries exactly one JSON document; status and progress go to stderr. List commands print the paginated response with data and pagination; others print only the resource or result. images pull, images build, and streaming projects commands print an array of progress frames when done.

Commands that remove or reset resources ask for confirmation. Add --yes to skip prompts in unattended scripts; on delete commands, --force also works.

--all (-a) returns every item, ignoring pagination. It can’t be combined with --limit or --start:

Terminal window
arcane-cli containers list --all --json

Arcane 3.0 removed these old flag names, so scripts using them fail with unknown flag. They clashed with the global --env (now --agent), --config, and --output flags, or were separate off switches.

Command Old flag New flag
containers create --env --env-var, -e
admin notifications settings set --config --provider-config
templates download --output --output-file, -o
agents create, agents update, registries create, registries update, templates registries update, admin federated create, admin federated update, admin backups policies update --disabled --enabled=false