Tillered Docs | CLI configuration reference

The Arctic CLI stores cluster connection details and global preferences in a YAML file. This page documents that file; for the cluster's declarative state file, see the compose file reference.

File location

Default: ~/.config/arctic/config.yaml (or $XDG_CONFIG_HOME/arctic/config.yaml).

Override with the --config flag or the ARCTIC_CONFIG environment variable.

Format

Peers are grouped by cluster. Each cluster carries a shared OAuth credential that works across all of its peers.

current_cluster: clu_01HABCDEF456...

clusters:
  clu_01HABCDEF456...:
    cluster_id: clu_01HABCDEF456...
    customer_id: cust_xyz789...
    client_id: cli_01HXYZ...
    client_secret: sec_abc123...
    peers:
      - peer_id: peer_01HXYZABC123...
        name: agent-a
        endpoints:
          - http://192.168.1.10:8080
      - peer_id: peer_01HXYZDEF789...
        name: agent-b
        endpoints:
          - http://192.168.1.20:8080
    default_peer: peer_01HXYZABC123...
    name: Production

preferences:
  output_format: table
  timeout: 30
  cache_ttl: 3600
  backup_retention: 5

A config bootstrapped before v1.4.2 may hold http:// endpoints like the example above. As of v1.4.2 the CLI rewrites a saved http:// endpoint to https:// on startup when the host is both known to its trust store and answers a live TLS handshake, and persists the change. The live probe keeps it from ever upgrading a genuinely plaintext peer; the rewrite is idempotent and only acts during the transition to peer TLS.

Cluster entry

Field	Type	Description
`cluster_id`	string	Cluster identifier (`clu_` prefix)
`customer_id`	string	Customer identifier from the license (`cust_` prefix)
`client_id`	string	Shared OAuth client ID (`cli_` prefix)
`client_secret`	string	Shared OAuth client secret (`sec_` prefix)
`peers`	array	Peers in this cluster
`default_peer`	string	Peer ID used by default; falls back to the first peer when empty
`name`	string	Optional human-friendly alias
`description`	string	Optional longer description

After a v1.4.2 bootstrap, client_id/client_secret hold a scoped working credential: everything routine CLI work needs, but no admin scope and no credential mutation. The break-glass admin pair is never written to this file; bootstrap writes it to break-glass.<cluster-id>.json next to the config (move it offline), and admin-only operations supply it per invocation via --client-id/--client-secret or ARCTIC_CLIENT_ID/ARCTIC_CLIENT_SECRET.

Peer entry

Field	Type	Description
`peer_id`	string	Peer identifier (`peer_` prefix)
`endpoints`	array	Ordered list of agent API URLs; the CLI tries them in order and remembers the last working one
`url`	string	Deprecated single-endpoint field, kept for older configs. `endpoints` wins when both are set
`name`	string	Optional human-friendly alias
`client_id`	string	Optional per-peer OAuth client ID; falls back to the cluster credential
`client_secret`	string	Optional per-peer OAuth client secret; falls back to the cluster credential

Preferences

Global CLI preferences. Every key is optional; defaults apply when unset.

Field	Type	Default	Description
`output_format`	string	`table`	Default output format: `table`, `json`, or `yaml`. Overridden by `--output`
`color`	boolean	`true`	Colored terminal output. Disabled automatically when `NO_COLOR` is set
`timeout`	integer	`30`	Default request timeout in seconds. Overridden by `--timeout`
`cache_ttl`	integer	`3600`	Completion cache TTL in seconds
`auto_failover`	boolean	`false`	Reserved; not yet implemented
`backup_retention`	integer	`5`	Number of `.arctic/backup/` snapshots `compose apply` keeps before pruning the oldest. As of v1.4.2 retention counts snapshots, where each snapshot is the state-plus-config pair captured before a non-bootstrap apply (a rollback point). Valid range 1-100 (0 means "use the default")

Managing the config

arctic config current                  # show the current cluster
arctic config use-cluster Production    # switch clusters
arctic config list                      # list clusters and peers
arctic config view                      # print the full config file

Security

The config file holds credentials in plaintext. Restrict its permissions:

chmod 600 ~/.config/arctic/config.yaml

For CI/CD, prefer environment variables over a checked-in config:

export ARCTIC_URL=https://agent:8080
export ARCTIC_TOKEN=eyJ...
arctic peers list

As of v1.4.2 there is a simpler CI path: a project directory containing cluster.yaml plus ARCTIC_CLIENT_ID/ARCTIC_CLIENT_SECRET is a complete setup. Commands run from that directory resolve their target from the compose file (endpoints and declared fingerprints included), so no config file is needed at all. See target resolution in the CLI reference.

CLI configuration reference