CLI Configuration

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

Set up the CLI

1. Create a starter config file with arcane-cli config init.
2. Set your server URL with 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 to sign in through your identity provider in a browser. Your server needs OIDC set up.

arcane-cli auth login

The session is saved to ~/.arcanecli/auth.json, not the config file (see Auth file). Device-code login can’t complete an MFA challenge, so with passkey MFA on, use an API key. 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. Page size comes from, in order: --limit on the command, pagination.resources.<resource>.limit, pagination.default.limit, then 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 (see the example below). 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.

Work across environments

Commands cover every enabled environment your server shows you, including local Docker. Pass --env <id> to limit a read to one environment or choose where a create goes:

arcane-cli containers list
arcane-cli --env 2 containers list

Authentication, config, environments, registries, repositories, templates, variables, and system backups aren’t tied to an environment, so --env doesn’t change them.

Lists

Container, image, volume, network, project, and vulnerability lists print one table with an ENVIRONMENT column. They read up to the server’s Environment limit (64 by default) in one request; environments beyond it or that failed are reported on stderr. With --json they print the server’s merged response, with failures in failedEnvironments.

Other reads run in each environment in turn. With --json they print one document that wraps each environment’s result:

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

A failed environment has error instead of result, success is false, and the command exits nonzero.

Actions on one resource

Commands that take a resource name or ID, such as containers restart nginx, search every environment. One match runs right away, and stderr shows which environment was picked. Several matches open a picker, or fail without a terminal or with --json until you pass --env.

Creates, imports, builds, image pulls and uploads, and conversions need a destination. In a terminal the CLI asks you to pick one; otherwise pass --env.

Changes in every environment

Prune, update checks, updater runs, settings and schedule updates, and similar changes ask <command> in all N environments? once, then run in each environment in turn. --yes or --force skips the question. A failure in one environment doesn’t stop the others, but the command exits nonzero.

If your credentials can’t list environments, for example an API key limited to one environment, the CLI stops with these credentials cannot list environments; pass --env <id> to choose one.

Verify self-update signatures

Preview

Important

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

Turn this preview on so arcane-cli 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.

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

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.

Network access and caching

The first verified 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.

Older releases

Releases before v1.18.0 are unsigned and can’t be installed with this preview on. Turn it 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, then see a typical file below:

arcane-cli config path

previews:
  newSelfUpdater: false
api_key: ''
cli_update_channel: stable
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. Since 3.0 the CLI ignores these keys and only reads sessions from auth.json. If your session only lives in those keys, sign in again with arcane-cli auth login.

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>	Limit the command to one environment. Without it, commands cover all environments.
--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.