CLI

Full reference for all akio commands and flags.

Overview

akio <COMMAND>

Akio is invoked via the akio binary. Every feature is exposed through a subcommand.

---

akio pull

Download a model repository from Hugging Face.

akio pull <REPO>

Argument	Description
REPO	Hugging Face repository slug, e.g. ggml-org/Qwen3-8B-GGUF

Examples

akio pull Fastiraz/Qwen3-0.6B-GGUF
akio pull Fastiraz/Qwen3.5-9B-GGUF

Files are stored in Akio’s local model directory. Use akio list to see what’s downloaded.

---

akio run

Start an interactive autonomous agent session with a model.

akio run -m <MODEL> [-c <CONTEXT_SIZE>] [--ngl <N_GPU_LAYERS>]

Flag	Default	Description
-m <MODEL>	(required)	Path or filename of the GGUF model to load
-c <CONTEXT_SIZE>	8192	Context window size in tokens
--ngl <N_GPU_LAYERS>	99	Number of transformer layers to offload to GPU (set 0 for CPU-only)
--verbose <LEVEL>	error	Log verbosity: none, debug, info, warn, error

Examples

# Basic run
akio run -m Fastiraz/Qwen3.5-9B-GGUF

# CPU-only with smaller context
akio run -m Fastiraz/Qwen3.5-9B-GGUF -c 4096 --ngl 0

# Full GPU offload, large context
akio run -m Fastiraz/Qwen3.5-9B-GGUF -c 16384 --ngl 99

The --ngl flag requires Akio to be compiled with CUDA or Metal support. If built for CPU only, this flag has no effect.

---

akio rm

Remove a previously downloaded model repository.

akio rm <REPO>

Argument	Description
REPO	Hugging Face repository slug to remove, e.g. ggml-org/Qwen3-0.6B-GGUF

Example

akio rm Fastiraz/Qwen3.5-9B-GGUF

---

akio list

List downloaded models. Aliased as akio ls.

akio list [--all]

Flag	Description
--all	Show every individual GGUF file instead of just repository names

Examples

akio list        # Show repositories
akio ls          # Same as above
akio list --all  # Show individual GGUF files

---

akio image

Generate an image from a text prompt using a local diffusion model. Aliased as akio img.

akio image -m <MODEL> --prompt <PROMPT> [OPTIONS]

Flag	Type	Default	Description
-m, --model	string	(required)	HuggingFace repo or alias of the model to use (e.g. turbo)
--prompt	string	(required)	Text prompt describing the image
--negative-prompt	string	""	Prompt to steer generation away from
--height	usize	model default	Output height in pixels (must be divisible by 16)
--width	usize	model default	Output width in pixels (must be divisible by 16)
--num-steps	usize	model default	Number of denoising steps
--guidance-scale	f64	model default	Classifier-free guidance (CFG) scale
--seed	u64	random	Seed for reproducible outputs
--output	string	output.png	Output filename
--cpu	flag	false	Force CPU inference instead of GPU

Examples

# Basic generation
akio image --model turbo --prompt "a cute orange cat sitting on a rooftop at sunset, studio ghibli-style"

# Custom resolution and seed
akio img \
  --model turbo \
  --prompt "a futuristic city skyline, neon lights, cinematic" \
  --width 1024 \
  --height 576 \
  --seed 42 \
  --output city.png

# With negative prompt
akio img \
  --model turbo \
  --prompt "a serene mountain lake at dawn, photorealistic" \
  --negative-prompt "blurry, low quality, distorted" \
  --guidance-scale 3.5 \
  --output lake.png

# CPU-only inference
akio img \
  --model turbo \
  --prompt "a red panda in a bamboo forest" \
  --cpu \
  --output panda.png

Width and height must both be divisible by 16. GPU is used by default when available (Metal on macOS, CUDA on Linux/Windows). Pass --cpu to override.

---

akio embedding

Generate L2-normalized vector embeddings from one or more input texts using a local GGUF embedding model. Aliased as akio embed.

akio embedding -m <MODEL> [--ngl <N_GPU_LAYERS>] <INPUT>...

Flag	Default	Description
-m <MODEL>	(required)	Path or filename of the GGUF embedding model
--ngl <N_GPU_LAYERS>	99	Number of layers to offload to GPU (set 0 for CPU-only)
--verbose <LEVEL>	error	Log verbosity: none, debug, info, warn, error
<INPUT>...	(required)	One or more input strings to embed (pass multiple as separate arguments)

The command prints a JSON array of float vectors — one vector per input — each L2-normalized.

Examples

# Single input
akio embedding -m Fastiraz/Qwen3-Embedding-0.6B-GGUF "Hello, world!"

# Multiple inputs at once
akio embed \
  -m Qwen3-Embedding-0.6B-Q8_0.gguf \
  "The cat sat on the mat" \
  "A quick brown fox"

# CPU-only
akio embed -m Fastiraz/Qwen3-Embedding-0.6B-GGUF --ngl 0 "embed this on CPU"

Use a model specifically trained for embeddings. The supported model is Fastiraz/Qwen3-Embedding-0.6B-GGUF. Pull it with akio pull Fastiraz/Qwen3-Embedding-0.6B-GGUF.

---

akio mcp

Manage MCP (Model Context Protocol) servers that extend Akio’s tool set.

akio mcp <ACTION>

akio mcp list

List all registered MCP servers and the tools they expose.

akio mcp list

akio mcp add

Register a new MCP server.

akio mcp add --name <NAME> --command <COMMAND> --args <ARGS...>

Flag	Description
--name <NAME>	Friendly name for the server (e.g. browser-use)
--command <COMMAND>	Executable to spawn (e.g. uvx, node, npx)
--args <ARGS...>	Arguments passed to the command

Example

akio mcp add --name browser-use --command uvx --args "browser-use"

akio mcp remove

Unregister an MCP server.

akio mcp remove --name <NAME>

Example

akio mcp remove --name browser-use