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.
Sign in
Section titled “Sign in”Log in interactively with the device-code flow:
arcane-cli auth loginCheck who you’re signed in as, or sign out:
arcane-cli auth mearcane-cli auth logoutFor CI, use an API key or a federated credential instead. See Federated Credentials.
Agents
Section titled “Agents”Commands cover every agent by default. Use --agent for only one:
arcane-cli containers list --agent 2Changes without --agent ask for confirmation before they run on all agents. See Work across agents.
List agents and check one is reachable:
arcane-cli agents listarcane-cli agents test 2Close an agent’s tunnel so it reconnects. Needs environments:restart:
arcane-cli agents tunnel restart 2Add 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:
arcane-cli agents create --name productionContainers
Section titled “Containers”arcane-cli containers listarcane-cli containers get my-containerarcane-cli containers restart my-containerList containers with a newer image available:
arcane-cli containers updatesPull the newer image and recreate the container:
arcane-cli containers update my-containerProjects
Section titled “Projects”arcane-cli projects listarcane-cli projects up my-projectarcane-cli projects down my-projectPull the latest images and restart:
arcane-cli projects redeploy my-projectRemove a project and its resources:
arcane-cli projects destroy my-projectVariables
Section titled “Variables”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:
arcane-cli variables create --key DOMAIN --value example.comPush variables to every agent now, or show the last sync result with --status:
arcane-cli variables syncImages and volumes
Section titled “Images and volumes”arcane-cli images listarcane-cli images pull nginx:latestReclaim space:
arcane-cli images prunearcane-cli volumes sizesFind out what’s using a volume before you remove it:
arcane-cli volumes usage my-volumeGitOps
Section titled “GitOps”arcane-cli gitops listarcane-cli gitops status my-syncarcane-cli gitops sync my-syncCreate 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.
arcane-cli gitops create --name my-app --mode bidirectional --repo-id <repo-id> --branch main --project my-app --backup-directory projects/my-appFor 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.
arcane-cli gitops preview my-apparcane-cli gitops history my-app --limit 20arcane-cli gitops resolve my-app --strategy use_repositoryAdd 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.
arcane-cli repos create --name my-repo --url https://git.example.com/me/stacks.git --provider giteaSystem
Section titled “System”Free up space on every agent, or pass --agent for one:
arcane-cli system pruneCheck whether an Arcane upgrade is available, and apply it:
arcane-cli system upgrade --checkarcane-cli system upgradeTurn a docker run command into Compose:
arcane-cli system convert "docker run -d -p 8080:80 nginx"Vulnerabilities
Section titled “Vulnerabilities”Get a summary or the full findings list, scan an image now, or show one image’s findings:
arcane-cli images vulnerabilities summaryarcane-cli images vulnerabilities listarcane-cli images vulnerabilities scan nginx:latestarcane-cli images vulnerabilities image nginx:latestSilence a CVE you’ve reviewed (and list or undo ignores with ignored / unignore):
arcane-cli images vulnerabilities ignore CVE-2026-1234Users and access
Section titled “Users and access”Set a user’s role assignments. Add :<agent-id> to scope one to an agent:
arcane-cli admin roles assign <user-id> --role role_deployer:<agent-id>List a user’s assignments:
arcane-cli admin roles assignments <user-id>Map an OIDC claim value to a role:
arcane-cli admin oidc create --claim docker-admins --role role_adminRead the Event Log:
arcane-cli admin events list- Custom roles:
admin roles list,get,create,update,delete,permissions. - Assignments:
admin roles assignandassignments. - See Roles & Permissions.
System backups
Section titled “System backups”Manage Arcane system backups from the terminal:
arcane-cli admin backups listarcane-cli admin backups createarcane-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.
Podman
Section titled “Podman”These commands work on Podman agents; see Podman Overview for host requirements. Check what the host supports first:
arcane-cli podman statusPods take the same flags as podman pod create:
arcane-cli podman pods listarcane-cli podman pods create --name web -p 8080:80 --memory 512marcane-cli podman pods stop web --timeout 30arcane-cli podman pods delete web --forceInstall a Quadlet with any files it needs, then start its unit:
arcane-cli podman quadlets install web.kube --extra-file web.yamlarcane-cli podman quadlets start web.kubePlay, tear down, or generate Kubernetes YAML:
arcane-cli podman kube play web.yaml --replacearcane-cli podman kube down web.yamlarcane-cli podman kube generate web --type deployment --serviceCreate or replace a secret. Without --file, the CLI prompts for the value, or reads one line from stdin:
arcane-cli podman secrets create db-password --file ./db-password.txtarcane-cli podman secrets update db-passwordRun Podman auto-update. --dry-run needs Podman 6.2 or later:
arcane-cli podman autoupdate --dry-runActivities and webhooks
Section titled “Activities and webhooks”arcane-cli activities listarcane-cli activities get <activity-id>Manage webhooks, or fire one by its token:
arcane-cli webhooks listarcane-cli webhooks trigger <token>Updater
Section titled “Updater”Inspect the automatic updater, trigger a run, and view history:
arcane-cli updater statusarcane-cli updater runarcane-cli updater historyHistory 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.
Update the CLI
Section titled “Update the CLI”arcane-cli self-update runSwitch between the stable and next release channels:
arcane-cli self-update channel nextself-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 problems and set up your shell
Section titled “Diagnose problems and set up your shell”Diagnose connectivity and configuration problems, install shell completion, or generate secrets and certificates for a new install:
arcane-cli doctorarcane-cli completion zsharcane-cli generate secretScripting
Section titled “Scripting”Every command accepts --output json (or --json), so you can pair it with jq:
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:
arcane-cli containers list --all --jsonRenamed flags
Section titled “Renamed flags”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 |