arctic cache

Manage the completion cache used for fast shell completions.

Synopsis

arctic cache <subcommand> [flags]

The cache command manages the local completion cache that stores peer and service data for fast shell completions.

Subcommands

refresh

Refresh the completion cache from the cluster.

arctic cache refresh [flags]

Fetches peer and service data from configured agents and stores it locally. By default, refreshes only the current cluster context.

Behavior:

1. Connects to agents in the cluster
2. Fetches peer list via /v1/peers API
3. Fetches service list via /v1/services API
4. Stores data in cache file at ~/.cache/arctic/completion.json
5. Updates cache timestamp

If multiple peers are configured, refresh tries each until one succeeds.

Flags:

Examples:

# Refresh current cluster
arctic cache refresh

# Refresh with JSON output
arctic cache refresh --output json

Output:

Table format shows:

• Cluster ID (truncated)
• Peer used for refresh
• Number of peers cached
• Number of services cached
• Status (success/failed)
• Duration in milliseconds
• Error message (if failed)

JSON format provides full refresh result with per-cluster details.

Exit Codes:

• 0: All clusters refreshed successfully
• 1: General error (config not found, permission denied)
• 4: All clusters unreachable
• 6: Partial failure (some clusters unreachable)

status

Show the current cache status.

arctic cache status [flags]

Displays cache location, age, TTL, staleness, and contents.

Flags:

Examples:

# Human-readable status
arctic cache status

# JSON output
arctic cache status --output json

Output:

Human-readable format shows:

Cache Location: /Users/user/.cache/arctic/completion.json
Last Updated:   2025-12-09T03:37:33Z (1h ago) [STALE]
TTL:            1h

Hint: Cache is older than TTL. Run 'arctic cache refresh' to update.

Cluster: clu_01KBYMHMRJ92E090...
  Peers:    2
  Services: 4

If the cache is stale (age > TTL), a [STALE] indicator appears with a hint to refresh.

JSON format provides structured data:

{
  "version": 1,
  "cache_location": "/Users/user/.cache/arctic/completion.json",
  "exists": true,
  "last_updated": "2025-12-09T03:37:33.880134Z",
  "age_seconds": 3987,
  "ttl_seconds": 3600,
  "is_stale": true,
  "clusters": [
    {
      "cluster_id": "clu_01KBYMHMRJ92E090P50VRKG4ZC",
      "peer_count": 2,
      "service_count": 4
    }
  ]
}

Exit Codes:

• 0: Success

delete

Delete the completion cache file.

arctic cache delete [flags]

Removes the cache file from disk. Completions will fall back to config file data until the cache is refreshed again.

Flags:

Examples:

# Interactive deletion with confirmation
arctic cache delete

# Skip confirmation
arctic cache delete --yes

# JSON output
arctic cache delete --output json

Output:

Human-readable format shows:

About to delete cache:
  Location: ~/.cache/arctic/completion.json
  Clusters: 2

Continue? [y/N]: y
Cache deleted: ~/.cache/arctic/completion.json

If the cache does not exist:

Cache already cleared: ~/.cache/arctic/completion.json

JSON format provides structured result:

{
  "version": 1,
  "cache_location": "~/.cache/arctic/completion.json",
  "existed": true,
  "deleted": true
}

Exit Codes:

• 0: Success
• 1: General error (permission denied)

Global Flags

These flags can be used with any subcommand:

See Global Flags for details.

Cache Location

The cache follows the XDG Base Directory specification:

• If $XDG_CACHE_HOME is set: $XDG_CACHE_HOME/arctic/completion.json
• Otherwise: ~/.cache/arctic/completion.json

Cache TTL

The cache TTL (Time To Live) is configured in the preferences section of the config file:

preferences:
  cache_ttl: 3600  # seconds (1 hour)

Default: 3600 seconds (1 hour)

See CLI Configuration - Preferences for details.

How Completions Use the Cache

Shell completions follow this process:

1. Check if cache exists at ~/.cache/arctic/completion.json
2. If cache exists and is not stale (age < TTL):
   • Read peer and service data from cache
   • Provide completions instantly (no API calls)
3. If cache is missing or stale:
   • Fall back to config file data (peer IDs/names only)
   • Suggest running arctic cache refresh

This cache-first approach ensures fast completions while keeping data reasonably fresh.

Cache Contents

The cache stores per-cluster:

• Peers: ID, name, URL, local flag, cached timestamp
• Services: ID, source peer ID, target peer ID, cached timestamp

The cache does NOT store:

• OAuth credentials (client ID/secret)
• Access tokens
• Private keys

Permissions

The cache file is created with restrictive permissions:

• File mode: 0600 (read/write for owner only)
• Directory mode: 0700 (accessible by owner only)

Examples

Basic Workflow

# Check cache status
arctic cache status

# If stale or missing, refresh
arctic cache refresh

# Verify update
arctic cache status

Troubleshooting Completions

# Delete stale cache
arctic cache delete --yes

# Refresh from agents
arctic cache refresh

# Test completions
arctic peers list <TAB>

Automated Refresh

Add to crontab for periodic refresh:

# Refresh cache every hour
0 * * * * /usr/local/bin/arctic cache refresh --yes

See Also

• Completion Cache Concept
• completion Command
• CLI Configuration
• Global Flags