IPC Commands Reference¶

Axium's daemon exposes an IPC protocol over a Unix domain socket for communication between CLI commands, spokes, and gears. This document catalogs all available IPC commands.

Use API Instead

Spokes and gears should use axium.core.api instead of direct IPC calls.

The API provides better error handling, type safety, and future compatibility. Only use direct IPC for:

Core daemon internal operations
Debugging and testing
Understanding the underlying protocol

See API Reference for the recommended high-level interface.

Connection¶

Socket Path: ~/.config/axium/daemon.sock
Protocol: JSON over Unix socket (newline-delimited)
Client Library: axium.core.ipc.send_request_sync(payload, timeout=2.0)

Command Format¶

All commands follow this structure:

{
    "cmd": "command_name",
    # Additional parameters...
}

Responses follow this structure:

{
    "ok": True,  # or False
    # Additional response data...
}

Core Commands¶

ping¶

Check if daemon is alive.

Request:

{"cmd": "ping"}

Response:

{"ok": True, "pong": True}

Example:

from axium.core.ipc import send_request_sync
response = send_request_sync({"cmd": "ping"})
# {"ok": True, "pong": True}

get_state¶

Get full daemon state (active environment, panes, uptime, etc.).

Request:

{"cmd": "get_state"}

Response:

{
    "ok": True,
    "state": {
        "active_env": "prod",
        "started": 1697123456.789,
        "panes": {"%1": {"env": "dev"}, ...}
    }
}

daemon_status¶

Get daemon status summary.

Request:

{"cmd": "daemon_status"}

Response:

{
    "ok": True,
    "status": {
        "running": True,
        "uptime": "2h 15m 30s",
        "active_env": "prod",
        "panes": 3
    }
}

stop¶

Stop the daemon gracefully.

Request:

{"cmd": "stop"}

Response:

{"ok": True, "stopping": True}

Note: Connection closes immediately after response. Daemon exits cleanly.

Environment Management¶

set_env¶

Set the active environment globally.

Request:

{"cmd": "set_env", "value": "prod"}

Response:

{"ok": True}

Side Effects: - Saves state to disk - Invalidates all config caches - Emits env_change event with (new_env, old_env)

Example:

response = send_request_sync({"cmd": "set_env", "value": "staging"})
# Spokes receive env_change event automatically

set_pane_env¶

Set environment override for a specific tmux pane.

Request:

{"cmd": "set_pane_env", "pane": "%3", "env": "dev"}

Response:

{"ok": True}

Use Case: Different environments in different tmux panes.

get_pane_env¶

Get environment for a specific pane (returns override or global).

Request:

{"cmd": "get_pane_env", "pane": "%3"}

Response:

{"ok": True, "env": "dev"}

clear_pane_env¶

Clear environment override for a pane (falls back to global).

Request:

{"cmd": "clear_pane_env", "pane": "%3"}

Response:

{"ok": True}

HUD System¶

get_hud¶

Render HUD string for a specific pane.

Request:

{"cmd": "get_hud", "pane": "%3"}

Response:

{
    "ok": True,
    "hud": "[axium] env:prod  uptime:2h15m  creds:Y"
}

Notes: - HUD is rendered fresh on each call (includes dynamic uptime) - Falls back to [axium] inactive on error - Used by axium hud command and tmux status-right

Configuration¶

get_config¶

Get configuration value by key.

Request:

{"cmd": "get_config", "key": "hud"}

Response:

{
    "ok": True,
    "value": {
        "style": {
            "wrapper": {"left": "[", "right": "]"},
            "theme": {"enabled": True, "name": "teal"}
        }
    }
}

Available Keys: - hud - HUD configuration from ~/.config/axium/hud.yaml - Spoke configs (via spoke-specific loaders)

reload¶

Reload all configuration and refresh caches.

Request:

{"cmd": "reload"}

Response:

{"ok": True, "reloaded": True}

Side Effects: - Reloads state from disk - Reloads HUD config - Reloads prefix config - Reloads all spoke configs - Regenerates state cache - Refreshes HUD cache for all panes - Emits events: hud_refresh, daemon_reload, config_reloaded

Use Case: Apply config changes without restarting daemon.

Prefix System¶

apply_prefixes¶

Apply prefix rules to a command.

Request:

{
    "cmd": "apply_prefixes",
    "command": "kubectl",
    "args": ["get", "pods"],
    "context": {"env": "prod"}
}

Response:

{
    "ok": True,
    "command": ["kubectl", "--context=prod-cluster", "get", "pods"],
    "env_vars": {"KUBECONFIG": "/path/to/prod.kubeconfig"}
}

list_prefixed_commands¶

List all commands that have prefix rules.

Request:

{"cmd": "list_prefixed_commands"}

Response:

{
    "ok": True,
    "commands": ["kubectl", "terraform", "aws"]
}

register_prefix¶

Register a new prefix rule dynamically.

Request:

{
    "cmd": "register_prefix",
    "command": "kubectl",
    "strategy": "args_append",
    "config": {"args": ["--context={{env}}"]}
}

Response:

{"ok": True}

Strategies: - args_append - Append arguments - args_prepend - Prepend arguments - env_vars - Set environment variables - wrapper - Wrap command in another command

Spoke Management¶

reload_spoke¶

Reload a specific spoke.

Request:

{"cmd": "reload_spoke", "spoke": "creds"}

Response:

{"ok": True, "spoke": "creds"}

Side Effects: - Reloads spoke Python module - Re-registers spoke commands and event handlers - Emits spoke_reloaded event with spoke_name

reload_spokes¶

Reload all spokes.

Request:

{"cmd": "reload_spokes"}

Response:

{
    "ok": True,
    "spokes": ["creds", "tmux-workflow", "aws-sso"]
}

Side Effects: - Reloads all spoke modules - Emits spoke_reloaded event for each spoke

Permissions (Gears Only)¶

get_permissions¶

Get permissions for a specific gear.

Request:

{"cmd": "get_permissions", "gear": "my-gear"}

Response:

{
    "ok": True,
    "permissions": {
        "exec": True,
        "notify": True,
        "ipc": ["tmux_split_run", "notify"],
        "fs_read": ["~/.my-tool/**"],
        "fs_write": ["~/.my-tool/cache/**"]
    }
}

load_spoke_permissions¶

Load permissions manifest for a gear.

Request:

{"cmd": "load_spoke_permissions", "spoke": "my-gear"}

Response:

{"ok": True}

Note: Reads manifest.yaml from gear directory and caches permissions.

Notifications¶

notify¶

Send a notification (requires notify permission for gears).

Request:

{
    "cmd": "notify",
    "title": "Build Complete",
    "message": "Production deployment successful",
    "level": "info"
}

Response:

{"ok": True}

Levels: info, warning, error, success

notify_drain¶

Retrieve and clear pending notifications.

Request:

{"cmd": "notify_drain"}

Response:

{
    "ok": True,
    "notifications": [
        {"title": "...", "message": "...", "level": "info", "timestamp": 1697123456}
    ]
}

Use Case: HUD polling for inline notifications (Feature 9).

Tmux Integration (Gears Only)¶

tmux_split_run¶

Create a tmux split pane and run a command.

Request:

{
    "cmd": "tmux_split_run",
    "command": "tail -f /var/log/app.log",
    "split": "horizontal"  # or "vertical"
}

Response:

{"ok": True, "pane": "%5"}

Requires: tmux_split_run in gear's ipc permissions.

tmux_send_keys¶

Send keys to a tmux pane.

Request:

{
    "cmd": "tmux_send_keys",
    "pane": "%5",
    "keys": "echo hello\n"
}

Response:

{"ok": True}

tmux_capture_pane¶

Capture content from a tmux pane.

Request:

{
    "cmd": "tmux_capture_pane",
    "pane": "%5",
    "start": -10,  # Last 10 lines
    "end": -1
}

Response:

{
    "ok": True,
    "content": "captured pane content..."
}

File Operations (Gears Only)¶

read_file¶

Read a file (requires fs_read permission with matching path).

Request:

{
    "cmd": "read_file",
    "path": "/home/user/.my-tool/config.yaml"
}

Response:

{
    "ok": True,
    "content": "file contents..."
}

Error Response:

{
    "ok": False,
    "error": "Permission denied: path not in fs_read whitelist"
}

write_file¶

Write a file (requires fs_write permission with matching path).

Request:

{
    "cmd": "write_file",
    "path": "/home/user/.my-tool/cache/data.json",
    "content": "{\"key\": \"value\"}"
}

Response:

{"ok": True}

write_log¶

Write to daemon log file.

Request:

{
    "cmd": "write_log",
    "level": "info",
    "message": "Custom log message",
    "gear": "my-gear"
}

Response:

{"ok": True}

Levels: debug, info, warning, error

Process Execution (Gears Only)¶

daemon_exec¶

Execute a command in the daemon process (requires exec permission).

Request:

{
    "cmd": "daemon_exec",
    "command": ["git", "status"],
    "cwd": "/path/to/repo",
    "env": {"GIT_DIR": "/custom/git"}
}

Response:

{
    "ok": True,
    "stdout": "On branch main...",
    "stderr": "",
    "returncode": 0
}

Warning: Use sparingly. Commands run in daemon process with elevated privileges.

Usage Patterns¶

Core Spokes (No Permissions)¶

Core spokes have unrestricted access to all IPC commands:

from axium.core.ipc import send_request_sync

# Set environment
send_request_sync({"cmd": "set_env", "value": "prod"})

# Get HUD
hud = send_request_sync({"cmd": "get_hud", "pane": "%3"})
print(hud["hud"])

Gears (Permission-Restricted)¶

Gears must declare required permissions in manifest.yaml:

# manifest.yaml
permissions:
  exec: true
  notify: true
  ipc:
    - tmux_split_run
    - notify
  fs_read:
    - ~/.my-tool/**
  fs_write:
    - ~/.my-tool/cache/**

Then use API with automatic permission checking:

from axium.core import api

# Automatically checks permissions before sending IPC
api.notify("Build Complete", "Deploy succeeded")
api.tmux_split_run("tail -f /var/log/app.log")

Error Handling¶

Always handle IPC errors gracefully:

try:
    resp = send_request_sync({"cmd": "set_env", "value": "prod"}, timeout=2.0)
    if not resp.get("ok"):
        print(f"Error: {resp.get('error')}")
except Exception as e:
    print(f"IPC failed: {e}")

IPC Commands Reference¶

Connection¶

Command Format¶

Core Commands¶

ping¶

get_state¶

daemon_status¶

stop¶

Environment Management¶

set_env¶

set_pane_env¶

get_pane_env¶

clear_pane_env¶

HUD System¶

get_hud¶

Configuration¶

get_config¶

reload¶

Prefix System¶

apply_prefixes¶

list_prefixed_commands¶

register_prefix¶

Spoke Management¶

reload_spoke¶

reload_spokes¶

Permissions (Gears Only)¶

get_permissions¶

load_spoke_permissions¶

Notifications¶

notify¶

notify_drain¶

Tmux Integration (Gears Only)¶

tmux_split_run¶

tmux_send_keys¶

tmux_capture_pane¶

File Operations (Gears Only)¶

read_file¶

write_file¶

write_log¶

Process Execution (Gears Only)¶

daemon_exec¶

Usage Patterns¶

Core Spokes (No Permissions)¶

Gears (Permission-Restricted)¶

Error Handling¶

See Also¶