CLI Reference

CLI Reference

Relevant source files

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

• AGENTS.md
• CONTRIBUTING.md
• Makefile
• cmd/axis/exit.go
• cmd/axis/main.go
• cmd/axis/placement.go
• cmd/axis/profile.go
• cmd/axis/task.go
• cmd/axis/task_test.go
• cmd/axis/testdata/task_context_turboquant.golden
• hack/pr-review-cycle.sh
• hack/refresh-current-state.sh
• hack/test-lint-failclosed.sh

The axis binary is a single-entry point for cluster discovery, task execution, and AI-assisted operations. It follows a "snapshot-first" philosophy where commands prioritize observed state over cached assumptions cmd/axis/main.go:41-44. The CLI is organized into five functional groups: Cluster Operations, Task Management, Setup & Daemon, AI Assistance, and Metadata Utilities cmd/axis/main.go:63-82.

Command Hierarchy

AXIS uses the Cobra library to structure its command surface. Each command group is designed to bridge the gap between human intent and machine execution through a deterministic 5-layer stack AGENTS.md:92-103.

CLI Structure to Code Entity Mapping

The following diagram maps the high-level CLI groups to the internal logic that powers them.

CLI to Internal Logic Mapping

graph TD
    subgraph "CLI Surface (cmd/axis/)"
        ROOT["axis"]
        CLUSTER["cluster group"]
        TASK["task group"]
        SETUP["setup group"]
        AI["ai group"]
    end

    subgraph "Code Entities"
        RUNT["runtimectx.Load()"]
        EXEC["execution.RunGuarded()"]
        DAEMON["daemon.Server"]
        AGENT["agent.Agent"]
    end

    ROOT --> CLUSTER
    ROOT --> TASK
    ROOT --> SETUP
    ROOT --> AI

    CLUSTER -.->|Read State| RUNT
    TASK -.->|Write State| EXEC
    SETUP -.->|Manage Lifecycle| DAEMON
    AI -.->|Advisory| AGENT

Loading

Sources: cmd/axis/main.go:63-132, AGENTS.md:94-103

Exit Codes

AXIS uses specific exit codes to distinguish between configuration errors, infrastructure failures, and logical placement misses. This allows for reliable scripting and CI/CD integration.

Code	Constant	Meaning
0	ExitOK	Success.
1	ExitErrGeneric	Unspecified runtime error.
2	ExitErrConfigLoad	Failed to parse nodes.yaml or state files.
3	ExitErrNoNodesFit	Placement engine found no suitable nodes for the task.
4	ExitErrCommandFail	The executed task/command returned a non-zero exit code.
5	ExitErrContextWrite	Failed to inject AXIS_CONTEXT_FILE for task execution.
6	ExitErrIO	General filesystem or network I/O failure.

Sources: cmd/axis/exit.go:10-18

Major Command Groups

Cluster Inspection

These commands provide the read-only diagnostic surface. They are used to verify the "Fact Plane" (Layer 1) and the "Snapshot Plane" (Layer 2).

• axis facts: Collect raw hardware/software telemetry from nodes.
• axis status: View a high-level summary of node health and resource availability.
• axis doctor: Run diagnostic checks across the cluster.

For details, see Cluster Inspection Commands.

Task Management

The execution surface handles workload scheduling and deterministic placement. It uses the execution package to orchestrate safety checks and resource reservations cmd/axis/task.go:34-35.

• axis task run: Execute a command on the best-fit node.
• axis task place: Dry-run placement to see where a task would land.
• axis task context: Export cluster state as a context block for LLMs.

For details, see Task Management Commands.

Daemon and Serve

The daemon manages a background cache of the cluster snapshot to speed up placement decisions. It provides a local Unix socket or TCP API for other axis commands to consume cmd/axis/task.go:143.

• axis daemon start: Launch the background refresh process.
• axis serve: Start the HTTP API server.

For details, see Daemon and Serve Commands.

AI Assistance

Advisory surfaces that consume cluster state but do not possess execution authority. They use the internal/agent and internal/mcp packages to provide cluster-aware assistance AGENTS.md:124-128.

• axis chat: Interactive REPL with cluster-aware model routing.
• axis agent: Autonomous tool-calling loop for complex cluster tasks.
• axis mcp serve: Exposes cluster facts as tools via the Model Context Protocol.

For details, see AI Assistant Commands.

System Flow: From Command to Execution

The diagram below shows how a command like axis task run moves from the CLI layer through the internal safety and placement logic.

Task Execution Flow

sequenceDiagram
    participant CLI as cmd/axis/task.go
    participant PL as internal/placement
    participant SF as internal/safety
    participant EX as internal/execution
    participant TR as internal/transport

    CLI->>PL: InferRequirements(description)
    PL-->>CLI: TaskRequirements
    CLI->>SF: Evaluate(command)
    SF-->>CLI: SafetyVerdict
    CLI->>EX: RunGuarded()
    EX->>TR: SSHExecutor.Execute()
    TR-->>CLI: ExitCode + Output

Loading

Sources: cmd/axis/task.go:185-220, AGENTS.md:129-130, internal/execution/guarded.go:1-50 (implied by cmd/axis/task.go:34-35)

---