peers

Manage cluster peers.

Aliases: peer

Synopsis

arctic peers <subcommand> [flags]

Subcommands

Subcommand	Description
list	List all peers
get	Get peer details
add	Add a remote peer
update	Update peer metadata
delete	Delete a peer
remove-self	Remove local peer from cluster

list

List all peers in the cluster.

Usage

arctic peers list [flags]

Flags

Flag	Description
`--local`	Show only local peers
`--remote`	Show only remote peers

Required Scope

urn:tillered:arctic:peers.read

Examples

# List all peers
arctic peers list

# List only remote peers
arctic peers list --remote

# List with detailed JSON output
arctic peers list -j

Output

Default table output shows a compact view with essential information:

ID                              NAME                  ADDRESS
peer_01KBYMHC35F0N070F3XXMEZAZR  agent-1               192.168.3.251:8080
peer_01KBYMD32Z2RVDE3G5Y9M530QR  agent-2               10.10.40.95:8080

The ADDRESS field shows the host:port extracted from the peer's URL.

With -j or -o json, get full detailed output:

[
  {
    "id": "peer_01KBYMHC35F0N070F3XXMEZAZR",
    "name": "agent-1",
    "public_key": "qnGyPtol7lqzLYU3989eaC+K4xda0w9KXlcEOM9cSBQ=",
    "is_local": true,
    "address": "192.168.3.251:8080",
    "created_at": "2025-12-08T09:26:30Z"
  },
  {
    "id": "peer_01KBYMD32Z2RVDE3G5Y9M530QR",
    "name": "agent-2",
    "public_key": "LSEn9IofAl7w1hfB1LFGpRoXuxbcSvEoBUZTrGblieA=",
    "is_local": false,
    "address": "10.10.40.95:8080",
    "created_at": "2025-12-08T09:26:34Z"
  }
]

get

Get details of a specific peer.

Usage

arctic peers get <peer-id>

Arguments

Argument	Description
`peer-id`	Peer ID to retrieve

Required Scope

urn:tillered:arctic:peers.read

Example

arctic peers get 01HXYZDEF789...

Output

ID:          peer_01KBYMHC35F0N070F3XXMEZAZR
Name:        agent-1
Public Key:  qnGyPtol7lqzLYU3989eaC+K4xda0w9KXlcEOM9cSBQ=
Is Local:    Yes
Address:     192.168.3.251:8080
Created At:  2025-12-08 09:26:30 UTC

add

Add a remote peer to the cluster.

Usage

arctic peers add <peer-address> [flags]

Arguments

Argument	Description
`peer-address`	Address of peer to add (e.g., `192.168.1.20:8080`)

Flags

Flag	Description
`--name`	Human-readable name for the peer

Required Scope

urn:tillered:arctic:peers.write

Examples

# Add a peer
arctic peers add 192.168.1.20:8080

# Add with a name
arctic peers add 192.168.1.20:8080 --name "Production Server"

# Add with debug output
arctic peers add 192.168.1.20:8080 --debug

Behavior

Contacts the remote peer's API
Performs handshake (exchanges public keys)
Both peers verify signatures against the license
Peer is added to the local database
Remote peer adds local peer via gossip

Errors

Error	Description
`peer URL required`	Missing address argument
`peer already exists in cluster`	Duplicate peer
`handshake failed`	Peer unreachable or validation failed
`node limit exceeded`	License node limit reached

update

Update a peer's metadata.

Usage

arctic peers update <peer-id> [flags]

Arguments

Argument	Description
`peer-id`	Peer ID to update

Flags

Flag	Description	Default
`--name`	Human-readable name for the peer
`--qos`	Enable QoS for this peer	`true`

Required Scope

urn:tillered:arctic:peers.write

Examples

# Update peer name
arctic peers update 01HXYZDEF789... --name "Production Server 2"

# Disable QoS for a peer
arctic peers update 01HXYZDEF789... --qos=false

delete

Delete a peer from the cluster.

Usage

arctic peers delete <peer-id> [--yes]

Arguments

Argument	Description
`peer-id`	Peer ID to delete

Flags

Flag	Description
`--yes`	Skip confirmation prompt

Required Scope

urn:tillered:arctic:peers.write

Examples

# Delete with confirmation prompt
arctic peers delete 01HXYZDEF789...

# Delete without confirmation
arctic peers delete 01HXYZDEF789... --yes

Errors

Error	Description
`peer ID required`	Missing peer ID
`peer not found`	Peer does not exist
`cannot delete local peer`	Use `remove-self` instead

remove-self

Gracefully remove the local peer from the cluster.

Usage

arctic peers remove-self [--yes]

Flags

Flag	Description
`--yes`	Skip confirmation prompt

Required Scope

urn:tillered:arctic:admin

Behavior

Marks the local peer as deactivated
Broadcasts deactivation announcement to cluster
Other peers remove this peer from their databases
Services involving this peer become inactive

Example

arctic peers remove-self --yes

Output

Peer removed from cluster
Peer ID:     01HXYZABC123...
Version:     2
Active:      false

peers

On this page