axonml-cli

Overview

axonml-cli is the official command-line interface for the AxonML machine learning framework. The binary is named axonml and ships a single clap-derived subcommand tree that covers the full ML workflow: project scaffolding, training, evaluation, model conversion, quantization, dataset tooling, GPU management, benchmarking, an embedded terminal UI, optional inference server, optional Weights & Biases integration, dashboard/API-server lifecycle control, and (under the server-sync feature) authenticated sync with a running axonml-server.

Last updated: 2026-04-16 — version 0.6.1.

Features

• Project Management — Create new projects (new), initialize existing directories (init), and generate Rust training-project scaffolds (scaffold generate / scaffold templates).

• Training & Evaluation — Train from a config file (train), resume from a checkpoint (resume), evaluate a model (eval), run single-input prediction (predict), and produce HTML/JSON/text reports (report).

• Model Operations — Convert between formats (convert), export for deployment targets (export), inspect architecture (inspect), quantize to Q4/Q5/Q8/F16/F32 via quant convert, and introspect/benchmark quant levels (quant info, quant benchmark, quant list).

• Data Management — Upload, analyze, list, configure, preview, and validate datasets (data {upload,analyze,list,config,preview,validate}).

• Deployment — Optional REST inference server (serve, requires --features serve) plus dashboard/server lifecycle (start, stop, status, logs).

• Integrations — Kaggle dataset search/download (kaggle), optional Weights & Biases config (wandb, requires --features wandb), and pretrained-model hub (hub).

• Terminal UI — axonml tui launches the axonml-tui Ratatui interface with an optional model/dataset preloaded.

• GPU Support — gpu list, gpu info, gpu select, gpu bench, gpu memory, gpu status over wgpu-based device detection.

• Server Sync — With --features server-sync: login, logout, and sync talk to a live axonml-server over HTTPS to mirror training runs, models, and datasets between CLI and web interface.

• Bundling — zip create/extract/list for model+dataset bundles; rename model|data for safe renames; upload for pushing a model file into a workspace directory; load {model,data,both,status,clear} and analyze {model,data,both,report} for workspace-scoped inspection; bench {model,inference,compare,hardware} for performance sweeps.

Binary

The crate produces a single binary:

[[bin]]
name = "axonml"
path = "src/main.rs"

There is no axon alias target; users who want a shorter name should add a shell alias (alias axon='axonml').

Modules

Installation

Install from crates.io:

cargo install axonml-cli

Or build from source:

cargo build --release -p axonml-cli

The produced binary is target/release/axonml.

Cargo features

Defined in Cargo.toml:

• default = ["wandb", "kaggle", "dataset-api", "hub-download", "server-sync"]
• serve — enables the serve subcommand (pulls in tokio + axum)
• wandb — enables the wandb subcommand group
• kaggle — enables Kaggle HTTP client used by kaggle search/download
• dataset-api — remote dataset listing/downloads
• hub-download — HTTP downloads of pretrained weights
• server-sync — enables login, logout, sync and the api_client module (pulls in reqwest + tokio)

Command Reference

All commands below are defined in src/cli.rs and dispatched in src/main.rs.

Usage

Project Commands

# Create a new AxonML project
axonml new my-project --template default

# Initialize AxonML in an existing directory
axonml init --name my-project

# Generate a Rust training project scaffold
axonml scaffold generate my-trainer --template training --wandb

Training Commands

# Train a model from configuration
axonml train --config config.toml --data ./data/train --epochs 50 --device cuda:0

# Resume training from a checkpoint (requires --data)
axonml resume checkpoint.pt --data ./data/train --epochs 20 --lr 0.0001

# Evaluate model performance
axonml eval model.pt ./data/val --metrics accuracy,loss --batch-size 32

# Make predictions
axonml predict model.pt input.json --format json --top-k 5

Model Commands

# Inspect model architecture
axonml inspect model.pt --detailed --show-params 5

# Convert model formats (ferrite / onnx / safetensors)
axonml convert model.pt model.onnx --to onnx --optimize

# Export for deployment
axonml export model.pt ./deploy --format onnx --target cuda --quantize --precision fp16

# Quantize model (Q4_0, Q4_1, Q5_0, Q5_1, Q8_0, F16, F32)
axonml quant convert model.pt --target Q8_0 --output model_q8.axon

# Inspect or benchmark quant levels
axonml quant info model_q8.axon --detailed
axonml quant benchmark model.pt --iterations 10 --types Q4_0,Q8_0
axonml quant list

# Generate evaluation report
axonml report model.pt --data ./test --format html --confusion-matrix --loss-curves

Data Commands

# Analyze a dataset
axonml data analyze ./data --detailed --recommend

# Upload and configure dataset
axonml data upload ./images --data-type image --task classification --split 0.8,0.1,0.1

# Validate dataset structure
axonml data validate ./data --check-balance --check-missing

# Preview dataset samples
axonml data preview ./data --num-samples 10 --random

# Generate preprocessing config
axonml data config ./data --output data_config.toml

Workspace Commands

# Load model into workspace
axonml load model model.pt --name my-model

# Load dataset into workspace
axonml load data ./dataset --data-type tabular

# Load both at once
axonml load both --model model.pt --data ./dataset

# Workspace status / clear
axonml load status
axonml load clear

# Analyze loaded model/dataset
axonml analyze model --detailed --output report.json --format json
axonml analyze data --detailed --max-samples 10000
axonml analyze both --output compat.json

# Generate comprehensive report
axonml analyze report --format html --visualize --output analysis_report.html

Benchmarking

# Benchmark model performance
axonml bench model model.pt --iterations 100 --batch-size 1 --device cuda:0

# Benchmark at different batch sizes
axonml bench inference model.pt --batch-sizes 1,2,4,8,16,32 --iterations 50

# Compare multiple models
axonml bench compare "model1.pt,model2.pt,model3.pt" --iterations 50

# Benchmark hardware capabilities
axonml bench hardware --iterations 10

GPU Management

axonml gpu list
axonml gpu info
axonml gpu select cuda:0 --persistent
axonml gpu bench --all --iterations 10
axonml gpu memory
axonml gpu status

Hub & Kaggle Integration

# Pretrained model hub
axonml hub list
axonml hub info resnet50
axonml hub download resnet50 --force
axonml hub cached
axonml hub clear resnet50        # clear one
axonml hub clear                 # clear all

# Kaggle
axonml kaggle login --username USER --key API_KEY   # credentials saved to ~/.kaggle/kaggle.json with 0600 perms; key is NOT echoed back
axonml kaggle status
axonml kaggle search "image classification" --limit 20
axonml kaggle download username/dataset-name --output ./data
axonml kaggle list

Note: kaggle login writes credentials to ~/.kaggle/kaggle.json with Unix mode 0600 and deliberately does not echo the API key (or username) back to stdout to keep it out of shell history / CI logs. Run axonml kaggle status after login to confirm.

Dataset (NexusConnectBridge)

axonml dataset list --source kaggle
axonml dataset info mnist
axonml dataset search "language model" --source all --limit 20
axonml dataset download mnist --output ./data
axonml dataset sources

Server Sync (CLI <-> Webapp, feature server-sync)

# Login to AxonML server (defaults to http://localhost:3021)
axonml login
axonml login --server http://myserver:3021 --username me

# Check sync status or force re-sync
axonml sync --status
axonml sync --force

# Logout and clear stored credentials
axonml logout

Dashboard & Server

# Start dashboard and API server (default: API on 3000, dashboard on 8080)
axonml start --port 3000 --dashboard-port 8080

# Start only the API server, in foreground
axonml start --server --foreground

# Check service status
axonml status --detailed --format json

# View logs
axonml logs --follow --lines 100 --level info

# Stop services (SIGTERM; use --force for SIGKILL)
axonml stop
axonml stop --server --force

Bundles, rename, upload, TUI

# Create / extract / list bundles
axonml zip create --output bundle.axonzip --model model.pt --data ./data --include-config
axonml zip extract bundle.axonzip --output ./extracted --verbose
axonml zip list bundle.axonzip --detailed

# Rename
axonml rename model model.pt new_model.pt --force
axonml rename data ./dataset new_name --force

# Upload a model file into a workspace directory
axonml upload ./model.pt --name my-model --version latest --output ./models --inspect

# Launch TUI
axonml tui --model model.pt --data ./dataset

Weights & Biases (feature wandb)

axonml wandb login
axonml wandb status
axonml wandb config --api-key ... --entity my-team --project my-proj --log-frequency 50 --log-checkpoints true
axonml wandb enable
axonml wandb disable
axonml wandb logout

Inference Server (feature serve)

axonml serve model.pt --host 127.0.0.1 --port 8080 --workers 4 --batch --max-batch-size 32 --timeout 30000

Configuration

The CLI uses axonml.toml for project configuration. Example:

[project]
name = "my-ml-project"
version = "0.1.0"
description = "My machine learning project"

[training]
epochs = 50
batch_size = 32
learning_rate = 0.001
device = "cuda:0"
checkpoint_frequency = 1
output_dir = "./output"
num_workers = 4

[training.optimizer]
name = "adam"
weight_decay = 0.0001
beta1 = 0.9
beta2 = 0.999

[training.scheduler]
name = "cosine"
t_max = 50
eta_min = 0.00001
warmup_epochs = 5

[model]
architecture = "resnet18"
num_classes = 10
dropout = 0.1

[data]
train_path = "./data/train"
val_path = "./data/val"
val_split = 0.1
augmentation = true
shuffle = true
normalize = true

Global Options

# Enable verbose output (global flag)
axonml --verbose <command>

# Suppress all output except errors (global flag)
axonml --quiet <command>

Tests

# Unit tests
cargo test -p axonml-cli

# Integration tests (uses assert_cmd / predicates)
cargo test -p axonml-cli --test cli_integration_test

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.