Skip to content

Getting Started

Get up and running with Axium in minutes.

Installation

Install in editable mode:

pip install -e .

Shell Integration

Load Axium shell integration (adds the ax alias):

source bash/init.sh

Add this to your .bashrc or .zshrc to load automatically:

# Axium shell integration
[ -f ~/path/to/axium/bash/init.sh ] && source ~/path/to/axium/bash/init.sh

First Steps

1. Set an Environment (Daemon Auto-Starts)

The daemon automatically starts when you run any axium command:

axium env set prod

The daemon runs in the background and maintains your session state, handling IPC operations, events, and completion cache updates.

Note: You don't need to manually start the daemon - it starts automatically when needed.

2. Verify Daemon is Running

Check daemon status:

axium daemon status

3. View the HUD

axium hud

Output: 

[axium] env:prod aws:- uptime:5m

4. Test Shell Completions

Axium provides fast shell completions that auto-update:

axium env <TAB>      # Shows: get  list  set  show
axium daemon <TAB>   # Shows: logs  reload  start  status  stop

See Shell Completions for installation.

5. Launch the Palette

axium palette

The interactive palette provides quick access to common commands and Spoke actions.

Configuration

Axium automatically creates its configuration directory at ~/.config/axium/ on first run.

Contents:

  • axiumd.log — daemon log file
  • state.json — daemon state (env, aws profile, etc.)
  • spokes/ — installed plugin folders
  • envs.yaml — environment definitions
  • prefixes.yaml — command prefix mappings

Environment Variables

  • AXIUM_DEBUG=1 — enables verbose debug logs
  • AXIUM_HOME — override default config directory

Example Workflows

Switch Environment

axium env set builder
axium hud

Output: 

[axium] env:builder aws:- uptime:5m

Reload Daemon

Reload daemon configuration without restart:

axium daemon reload

View Logs

axium daemon logs -f

Development Setup

Requirements:

  • Python ≥ 3.9
  • Typer
  • PyYAML
  • pytest

Setup:

git clone https://github.com/axium-tools/axium.git
cd axium
pip install -e .[dev]
pytest -q

Next Steps