Skip to content

Cluster Inspection Commands

Jump to bottom
William Smith edited this page Jul 13, 2026 · 1 revision

Cluster Inspection Commands

Relevant source files

The following files were used as context for generating this wiki page:

The AXIS CLI provides a comprehensive read-only diagnostic surface for inspecting the state of individual nodes and the collective cluster. These commands leverage the Layer 1 (Fact Plane) and Layer 2 (Snapshot Plane) to provide deterministic visibility into hardware telemetry, software backends, and connectivity health.

Overview of Inspection Surface

Inspection commands primarily interact with two data sources:

  1. Live Discovery: Direct fan-out probing of nodes via SSH or local execution cmd/axis/status.go:54-62.
  2. Daemon Cache: A high-performance snapshot stored by the axis daemon, accessible via a Unix socket or TCP API cmd/axis/status.go:114-116.
Command Purpose Primary Data Source
axis facts Detailed telemetry for the local node LocalCollector
axis status Tabular overview of all cluster nodes ClusterSnapshot
axis summary Visual dashboard of cluster health/resources ClusterSnapshot + daemon.Metadata
axis doctor Connectivity and configuration validation SSH Probes + API Health Checks
axis task context Explains placement logic for a hypothetical task PlacementEngine + ClusterSnapshot

axis facts

The facts command executes a local collection cycle to display granular hardware and software details about the current machine.

Implementation Details

The command initializes a facts.NewLocalCollector cmd/axis/facts.go:17-19. It gathers:

Sources: cmd/axis/facts.go:1-172

axis status

The status command provides a cluster-wide view, aggregating NodeFacts from all configured members into a ClusterSnapshot.

Snapshot Resolution Logic

The command uses collectStatusSnapshot to resolve which data source to use based on CLI flags:

  • --cached: Attempts to hit the daemon API; falls back to live discovery if the daemon is unreachable cmd/axis/status.go:114.
  • --cached-only: Fails if the daemon is unreachable cmd/axis/status.go:115.
  • Live (Default): Performs a full network fan-out to all nodes defined in nodes.yaml.

Data Flow: Status Collection

"Code Entity Space" mapping for axis status:

graph TD
    subgraph "CLI Entry"
        A["axis status"] --> B["collectStatusSnapshot"]
    end

    subgraph "Data Sources"
        B --> C["daemon.FetchSnapshot"]
        B --> D["discoverLiveSnapshot"]
    end

    subgraph "Formatting"
        C --> E["printStatusText"]
        D --> E
        E --> F["RenderNodeTable"]
        E --> G["printResidentModelsSection"]
    end

    subgraph "Output"
        F --> H["Stdout"]
        G --> H
    end
Loading

Sources: cmd/axis/status.go:40-110, cmd/axis/status_test.go:12-43

Resident Model Display

The status command includes a specialized section for active LLMs. It groups models by their runtime (e.g., ollama, mlx) and truncates long lists to maintain terminal readability cmd/axis/status.go:188-199.

Sources: cmd/axis/status.go:188-240, cmd/axis/status_test.go:110-245

axis summary

The summary command provides a high-level visual dashboard. Unlike the tabular status, summary calculates aggregate cluster metrics.

Key Metrics

Visual Components

The command uses renderBar to create ASCII progress bars for RAM utilization cmd/axis/dashboard.go:209-214.

Sources: cmd/axis/dashboard.go:22-146, cmd/axis/testdata/summary_with_nodes.golden:1-21

axis doctor

The doctor command is the primary tool for troubleshooting cluster connectivity and environment parity.

Diagnostic Suite

  1. Config Validation: Checks for the existence and schema validity of nodes.yaml cmd/axis/doctor.go:120-128.
  2. SSH Connectivity: Performs an actual handshake with every remote node using transport.NewSSHExecutor to verify credentials and network paths cmd/axis/doctor.go:194-212.
  3. Daemon Health: Probes the local AXIS API socket to ensure the background process is responsive cmd/axis/doctor.go:216-230.
  4. Local Backend Probes: Executes discovery scripts (e.g., facts.OllamaDiscoveryScript) to verify if AI runtimes are not just installed, but actually running and responsive cmd/axis/doctor.go:43-100.

Code Mapping: Doctor Diagnostics

"Natural Language Space" to "Code Entity Space":

graph TD
    subgraph "Check: Configuration"
        Config["'Configuration File'"] --> Load["config.Load()"]
    end

    subgraph "Check: Connectivity"
        SSH["'SSH: {node}'"] --> Exec["transport.NewSSHExecutor"]
        Exec --> Conn["sshExec.Connect()"]
    end

    subgraph "Check: Daemon"
        Daemon["'Local Daemon'"] --> Fetch["daemon.FetchSnapshot"]
    end

    subgraph "Check: Backends"
        Backend["'Backend Probes'"] --> Probe["runBackendProbeScript"]
        Probe --> Script["facts.LlamaServerDiscoveryScript"]
    end
Loading

Sources: cmd/axis/doctor.go:115-230, cmd/axis/doctor_test.go:17-86

axis task context

While technically part of the task management suite, axis task context serves as a read-only "explainable AI" surface for the placement engine.

It accepts a natural language task description and performs a "Dry Run" of the placement pipeline. It outputs:

Sources: cmd/axis/task_command_test.go:137-168, cmd/axis/task_place_test.go:47-79

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally