CLI Commands

Complete reference for all axel CLI commands and options.

Launching

`axel`

Launch a workspace from the current directory. axel walks up the directory tree looking for a axel.yaml file and launches the configured session.

Usage

$ axel [SHELL]

Options

-m, --manifest-path <PATH>Path to axel.yaml (default: ./axel.yaml)

-p, --profile <PROFILE>Terminal profile to use (default: "default")

-w, --worktree <BRANCH>Create/use git worktree for branch

Examples

Launch full workspace from current directory

$ axel

Launch a specific shell from the manifest

$ axel claude

Launch with a specific profile

$ axel -p focus

Launch in a git worktree

$ axel -w feat/new-feature

Launch from a custom manifest

$ axel -m ./configs/dev.yaml

`axel -k, --kill <workspace>`

Kill a running workspace session. Terminates all panes, closes the tmux session, and cleans up any agent symlinks that were created.

Usage

$ axel -k <workspace>

Options

--keep-agentsKeep agent symlinks instead of cleaning them up

--pruneAlso remove the git worktree (use with -w)

Examples

Kill a running workspace

$ axel -k my-project

Kill but keep agent files

$ axel -k my-project --keep-agents

Kill workspace and remove worktree

$ axel -w feat/auth -k my-project-feat-auth --prune

Git Worktrees

Launch workspaces in isolated git worktrees for parallel branch development. Worktrees let you work on multiple branches simultaneously without stashing or switching.

`axel -w, --worktree <branch>`

Create or use a git worktree for the specified branch and launch the workspace from there. If the branch doesn't exist, it will be created from the default branch (main/master). The worktree is created as a sibling directory to your repository.

Usage

$ axel -w <branch>

Options

-w, --worktree <BRANCH>Branch name to create/use worktree for

Examples

Create worktree and launch workspace

$ axel -w feat/auth

Launch specific shell in worktree

$ axel -w feat/auth claude

Use existing worktree

$ axel -w feat/auth

How It Works

When you run axel -w feat/auth:

If the branch exists locally or on remote, a worktree is created for it
If the branch doesn't exist, it's created from your default branch
Your axel.yaml is symlinked to the worktree
The workspace launches from the worktree directory

~/code/

├── myproject/ # main repo

│ ├── axel.yaml

│ └── src/

└── myproject-feat-auth/ # worktree

├── axel.yaml → ../myproject/axel.yaml

└── src/

Setup

`axel init`

Initialize a axel workspace in the current directory. Creates a axel.yaml file with a basic configuration.

Usage

$ axel init

Examples

Initialize a new workspace

$ axel init

`axel bootstrap`

[Experimental] Scan your machine for existing agents and consolidate them using AI. We recommend using axel agent import for more control.

Usage

$ axel bootstrap

Examples

Auto-discover agents

$ axel bootstrap

Session Commands

Manage running axel tmux sessions. List active workspaces, create new ones, or kill existing sessions.

`axel session list`

List all running axel sessions. Shows session name, working directory, window count, and attachment status.

Usage

$ axel session list

Options

-a, --allShow all tmux sessions, not just axel sessions

Examples

List axel sessions

$ axel session list

List all tmux sessions

$ axel session ls --all

`axel session new`

Create a new workspace session. Equivalent to running `axel` or `axel <shell>`. Launches a workspace from the axel.yaml manifest in the current directory.

Usage

$ axel session new [SHELL]

Examples

Create new workspace

$ axel session new

Create with specific shell

$ axel session new claude

`axel session join <name>`

Attach to an existing axel or tmux session. If already inside tmux, switches to the target session.

Usage

$ axel session join <name>

Examples

Join a session

$ axel session join my-project

`axel session kill`

Kill a running workspace session. Equivalent to `axel -k <name>`. Terminates all panes, closes the tmux session, and cleans up agent symlinks.

Usage

$ axel session kill [NAME]

Options

--keep-agentsKeep agent symlinks instead of cleaning them up

Examples

Kill current session

$ axel session kill

Kill named session

$ axel session kill my-project

Kill but keep agents

$ axel session kill my-project --keep-agents

Agent Commands

Manage your portable agent files. See the Agents documentation for more details.

`axel agent list`

List all available agents, both local (in current workspace) and global (in ~/.config/axel/agents).

Usage

$ axel agent list

Examples

List all agents

$ axel agent list

Using the alias

$ axel agents ls

`axel agent import <path>`

Import an agent file or directory to the global agents directory. This makes the agent available across all your workspaces.

Usage

$ axel agent import <path>

Examples

Import a single agent file

$ axel agent import ./.claude/agents/web-developer.md

Import all agents from a directory

$ axel agent import ./agents/

`axel agent new [name]`

Create a new agent file. If no name is provided, you will be prompted.

Usage

$ axel agent new [name]

Examples

Create a new agent with name

$ axel agent new code-reviewer

Create interactively

$ axel agent new

`axel agent fork <name>`

Copy a global agent to the current workspace's local agents directory. This creates a local copy you can customize.

Usage

$ axel agent fork <name>

Examples

Fork a global agent locally

$ axel agent fork web-developer

`axel agent link <name>`

Create a symlink from the current workspace to a global agent. Changes to the global agent will be reflected locally.

Usage

$ axel agent link <name>

Examples

Link a global agent

$ axel agent link code-reviewer

`axel agent rm <name>`

Remove an agent file.

Usage

$ axel agent rm <name>

Examples

Remove an agent

$ axel agent rm old-agent

Other

`axel --version`

Display the current version of axel.

Usage

$ axel --version

Examples

Check version

$ axel --version

`axel --help`

Display help information and a list of all available commands.

Usage

$ axel --help

Examples

Show help

$ axel --help

CLI Commands

Launching

axel

Usage

Options

Examples

axel -k, --kill <workspace>

Usage

Options

Examples

Git Worktrees

axel -w, --worktree <branch>

Usage

Options

Examples

How It Works

Setup

axel init

Usage

Examples

axel bootstrap

Usage

Examples

Session Commands

axel session list

Usage

Options

Examples

axel session new

Usage

Examples

axel session join <name>

Usage

Examples

axel session kill

Usage

Options

Examples

Agent Commands

axel agent list

Usage

Examples

axel agent import <path>

Usage

Examples

axel agent new [name]

Usage

Examples

axel agent fork <name>

Usage

Examples

axel agent link <name>

Usage

Examples

axel agent rm <name>

Usage

Examples

Other

axel --version

Usage

Examples

axel --help

Usage

Examples

On this page

`axel`

`axel -k, --kill <workspace>`

`axel -w, --worktree <branch>`

`axel init`

`axel bootstrap`

`axel session list`

`axel session new`

`axel session join <name>`

`axel session kill`

`axel agent list`

`axel agent import <path>`

`axel agent new [name]`

`axel agent fork <name>`

`axel agent link <name>`

`axel agent rm <name>`

`axel --version`

`axel --help`