Completion Cache

The Arctic CLI uses a local completion cache to provide fast, responsive shell completions without making API calls during interactive use.

Overview

Shell completions need to respond quickly (typically under 100ms) to provide a good user experience. Calling the Arctic Agent API for every completion would be too slow, especially with multiple peers or network latency.

The completion cache solves this by storing peer and service data locally in a JSON file that shell completions can read instantly.

Cache Architecture

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 Contents

The cache stores:

• Peers: ID, name, URL, local flag, and health status per cluster
• Services: ID, source peer, target peer per cluster
• Metadata: Cache version, last update time

Example cache structure:

{
  "version": 1,
  "updated_at": "2025-12-09T14:30:00Z",
  "clusters": {
    "01HABCDEF456...": {
      "peers": [
        {
          "id": "peer_01HXYZABC123",
          "name": "Agent A",
          "url": "http://192.168.1.10:8080",
          "is_local": true,
          "cached_at": "2025-12-09T14:30:00Z"
        }
      ],
      "services": [
        {
          "id": "01HSERVICE123",
          "source_peer_id": "peer_01HXYZABC123",
          "target_peer_id": "peer_01HXYZDEF789",
          "cached_at": "2025-12-09T14:30:00Z"
        }
      ]
    }
  }
}

Cache Lifecycle

1. Cache Refresh

Populate the cache with fresh data from agents:

# Refresh current cluster
arctic cache refresh

The refresh operation:

1. Attempts to connect to each peer in the cluster
2. Fetches the peer list via /v1/peers
3. Fetches the service list via /v1/services
4. Stores the data in the cache file
5. Updates the timestamp

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

2. Cache Usage

Shell completions automatically use the cache:

• Check if cache exists and is fresh (age < TTL)
• If valid, read peer/service data from cache
• If missing or stale, fall back to config file data
• No API calls are made during completion

3. Cache Staleness

The cache has a configurable TTL (Time To Live):

• Default: 3600 seconds (1 hour)
• Configure via preferences.cache_ttl in config file
• Check staleness with arctic cache status

When the cache is stale:

• Completions still work using cached data
• A background refresh is recommended
• No automatic refresh (user must run arctic cache refresh)

Cache Operations

View Status

Check cache age, staleness, and contents:

# Human-readable status
arctic cache status

# JSON output
arctic cache status --output json

Output includes:

• Cache file location
• Last update time
• Age in seconds
• TTL setting
• Staleness indicator
• Per-cluster peer and service counts

Delete Cache

Remove the cache file:

# Interactive confirmation
arctic cache delete

# Skip confirmation
arctic cache delete --yes

# JSON output
arctic cache delete --output json

After deletion:

• Completions fall back to config file data
• Next refresh recreates the cache file

Configuration

Cache TTL

Set the cache TTL in your config file:

preferences:
  cache_ttl: 3600  # seconds (1 hour)

Permissions

The cache file is created with restrictive permissions:

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

Best Practices

When to Refresh

Refresh the cache after:

• Adding or removing peers
• Creating or deleting services
• Changing cluster membership
• Noticing stale completion suggestions

Automation

Consider refreshing the cache periodically via cron:

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

Multi-Cluster Setups

For environments with multiple clusters:

# Refresh all clusters at once
arctic cache refresh --all-contexts

This ensures completions work across all configured contexts.

Troubleshooting

If completions are not working:

1. Check cache status: arctic cache status
2. If stale, refresh: arctic cache refresh
3. If errors persist, delete and recreate: arctic cache delete --yes && arctic cache refresh

Performance

Cache read performance:

• File size: 1-10 KB per cluster (hundreds of peers/services)
• Read time: under 5ms on modern SSDs
• JSON parse time: under 1ms

This makes cache-based completions fast enough for interactive use.

Security Considerations

No Credentials

The cache does not store:

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

Only public metadata (peer IDs, service IDs, names) is cached.

File Permissions

The cache file is created with 0600 permissions to prevent other users from reading it, even though it contains no sensitive data.

Cache Invalidation

The cache does not auto-expire. Users must:

• Manually refresh when cluster state changes
• Monitor staleness via arctic cache status
• Configure automation if needed

See Also

• arctic cache CLI Reference
• CLI Configuration
• Completion Command