Skip to content

CLI Configuration

Point arcane-cli at your server, sign in, and choose which agents a command covers.

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>.

  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.

Use this to sign in through your identity provider in a browser. Your server needs OIDC set up.

Terminal window
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.

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

Terminal window
arcane-cli config set api-key arc_xxxxxxx

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:

Terminal window
arcane-cli config set default-limit 25
Terminal window
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, agents, registries, templates, repos, gitops-syncs, users, roles, events, and apikeys.

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

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

Terminal window
arcane-cli containers list
arcane-cli --agent 2 containers list

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

Container, image, volume, network, project, and vulnerability lists print one table with an AGENT column. They read up to the server’s Agent limit (64 by default) in one request; agents 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 on each agent in turn. With --json they print one document that wraps each agent’s result:

{
"success": true,
"agents": [
{
"agentId": "0",
"agentName": "Local Docker",
"result": { "success": true, "data": [] }
}
]
}

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

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

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

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

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

The config file is at ~/.config/arcanecli.yml by default. Print the exact path, then see a typical file below:

Terminal window
arcane-cli config path
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 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": "..."
}
}

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.

These flags work on every command.

Flag Purpose
--output <mode> Output mode, text or json. --json is an alias for --output json.
--agent <id> Limit the command to one agent. Without it, commands cover all agents.
--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.