CLI Configuration

arcane-cli keeps its server URL, credentials, and defaults in a YAML config file. Set it up once after you install the CLI, and change values later with arcane-cli config set <key> <value>.

Set up the CLI

1. Create a starter config file:

arcane-cli config init

2. Set your server URL:

arcane-cli config set server-url http://localhost:3552

3. Sign in with one of the methods below.

Sign in

With a device code

Use this when your Arcane server has OIDC set up and you want to sign in through your identity provider in a browser.

arcane-cli auth login

The CLI saves the session to ~/.arcanecli/auth.json, not the config file. See Auth file.

Device-code login can’t complete an MFA challenge. If your account has passkey MFA turned on, use an API key instead. See Passkeys & MFA.

With an API key

Use this for CI/CD, automation, or accounts with MFA.

arcane-cli config set api-key arc_xxxxxxx

Change list limits

List commands are paginated. The page size is chosen in this order:

1. --limit on the command
2. pagination.resources.<resource>.limit in the config
3. pagination.default.limit in the config
4. The command’s built-in default

Set limits from the CLI:

arcane-cli config set default-limit 25

arcane-cli config set pagination.resources.containers.limit 50 pagination.resources.images.limit 100

You can also edit pagination in the config file directly (see the example below). The resource names are containers, images, volumes, networks, projects, environments, registries, templates, repos, gitops-syncs, users, roles, events, and apikeys.

For doctor, shell completion, and other commands, see CLI Commands.

Preview every environment

Preview

Important

All-environments mode is a preview feature. Its behavior, output, and JSON format are subject to change at any time.

Enable all-environments preview to list resources and perform actions without setting a default environment:

arcane-cli config set previews.allEnvironments true
arcane-cli containers list
arcane-cli containers start nginx

Preview includes the visible, enabled environments returned by your server, including local Docker. Text lists use one combined table with an ENVIRONMENT column containing each environment’s name, followed by a combined total. Structured details retain environment headings. Resources with identical names or IDs in different environments remain separate. List filters, sorting, limits, and --start apply separately to each environment. --all requests every matching item per environment and keeps its existing flag restrictions.

An explicit --env <id> overrides preview for one command. Your saved default environment is preserved; disabling preview restores it:

arcane-cli --env 0 containers list
arcane-cli config set previews.allEnvironments false

Authentication, environments, registries, repositories, templates, variables, and system backups retain their existing global scope.

Choose a resource or destination

Resource actions search every enabled environment. A unique confirmed match is selected automatically. Multiple matches open a Bubble Tea picker showing resource and environment details. If any search fails, even a single confirmed match requires explicit picker selection. Dependent resources, uploads, downloads, and restores stay in the selected environment.

Creation, imports, builds, image pulls and uploads, and conversion require a destination picker. JSON and noninteractive commands require --env whenever selection is necessary. --yes and --force never choose a resource or destination. Cancelling a picker sends no mutation.

Confirm a fleet operation

Environment-wide mutations run sequentially across enabled environments after one confirmation showing the operation and environment names. This covers prune, update checks, updater runs, bulk container start/stop, settings and schedule updates, and activity-history clearing. --yes and applicable existing confirmation-skip flags bypass confirmation.

Individual failures do not stop later environments, but the command exits nonzero if any operation fails. Cancellation prevents remaining operations from starting. Preview system upgrades use the existing fleet upgrade endpoint once; explicit --all retains its existing behavior.

Read aggregate JSON

Preview reads and fleet operations emit one JSON document. Each result retains that command’s existing JSON payload, including pagination and extra response fields:

{
  "success": true,
  "environments": [
    {
      "environmentId": "0",
      "environmentName": "Local Docker",
      "result": {
        "success": true,
        "data": [],
        "pagination": { "totalItems": 0 }
      }
    }
  ]
}

Failed entries contain error instead of result; aggregate success is false and the exit status is nonzero. Discovery failure stops the command. An empty enabled-environment list produces an empty successful read. Single-resource actions retain their existing JSON payload and announce the selected environment on stderr.

Verify self-update signatures

Preview

Important

Signature verification is a preview feature. Its behavior and output are subject to change at any time.

Every Arcane release signs its checksum file with the Arcane cosign key and records the signature in Sigstore’s public transparency log. With this preview on, arcane-cli self-update checks that signature before it trusts any checksum:

arcane-cli config set previews.newSelfUpdater true
arcane-cli self-update run

The CLI downloads the checksum file and its .sigstore.json bundle, then confirms the checksum file was signed with the Arcane key, is recorded in the transparency log, and has not changed. Only then does it check the downloaded binary against that checksum. The cosign key is built into the CLI, so you don’t need cosign installed.

If verification fails, the update stops and your binary is left unchanged. The CLI does not fall back to an unverified update. Verification also runs with --dry-run and --json, and the JSON output reports signatureVerified and bundleUrl.

Network access and caching

The first verified update downloads Sigstore’s trust data from tuf-repo-cdn.sigstore.dev. The CLI caches it in arcane-cli/sigstore under your user cache directory, which is ~/.cache on Linux and ~/Library/Caches on macOS. Later updates use the cache, including offline, until the trust data expires. After that the CLI needs to reach tuf-repo-cdn.sigstore.dev again.

Older releases

Releases before v1.18.0 are not signed, so you can’t install them with this preview on. To install one, turn the preview off first:

arcane-cli config set previews.newSelfUpdater false
arcane-cli self-update --version v1.17.4

A signature proves Arcane published a release. It does not stop you from installing an older signed release, for example with --version.

Reference

Config file

The config file is at ~/.config/arcanecli.yml by default. Print the exact path on your system with:

arcane-cli config path

A typical config file:

previews:
  allEnvironments: false
  newSelfUpdater: false
api_key: ''
cli_update_channel: stable
default_environment: '0'
federated_audience: ''
log_level: info
pagination:
  default:
    limit: 20
  resources:
    containers:
      limit: 50
    images:
      limit: 100
server_url: http://localhost:3552

Auth file

auth login, auth refresh, auth federated --persist, and config set jwt-token save session tokens to ~/.arcanecli/auth.json with owner-only permissions. With --json, auth login and auth refresh print the tokens instead of saving them. Tokens are stored per server URL, so a session for one server is never sent to another. auth logout removes the current server’s session.

{
  "https://arcane.example.com": {
    "accessToken": "eyJ...",
    "refreshToken": "..."
  }
}

Warning

Older versions saved jwt_token and refresh_token in the config file. These keys are deprecated and stop working in v3. The CLI still reads them and prints a warning. Run arcane-cli auth refresh to move the session to auth.json.

If auth.json is damaged, the CLI ignores it with a warning but can’t save new sessions. Run arcane-cli config backup --auth to move it to auth.json.bak, then sign in again.

API keys set with arcane-cli config set api-key stay in the config file. A config with an API key ignores saved sessions and always authenticates with the key.

Global flags

These flags work on every command.

Flag	Purpose
--output <mode>	Output mode, text or json. --json is an alias for --output json.
--env <id>	Select one environment, overriding preview and the configured default.
--yes, -y	Auto-confirm destructive prompts.
--no-color	Disable ANSI color output.
--request-timeout <duration>	Override the HTTP timeout for one command.
--config, -c <path>	Use a config file other than the default.
--log-level <level>	Set verbosity: debug, info, warn, error, or fatal.
--log-json	Emit structured JSON logs.