CLI reference

Every command, with what --help does not say. isx <command> --help lists all of its options.

isx

Launch the interactive TUI. Falls back to plain-text listing when stdout is not a terminal.

isx

isx init

One-time host setup: install Incus, configure credentials and their accounts, test connectivity. Safe to re-run, e.g. to add, rename or remove an account.

isx init

isx build

Build or rebuild a template image.

isx build [<template>...] [options]

A template's name may be at most 52 characters, since it is built as <name>-rebuilding first and swapped in once built; a longer one is refused before anything is built, its parents included.

Several templates build in one invocation: plainly, each in turn, a named parent before its child (each with any parent that is missing or out of sync, so a parent they share is built once); with --with-parents or --with-descendants, as one batch with one confirmation, parents before children and every template once. An unknown name anywhere in the list builds nothing. A target that fails does not stop the others: one that inherits from it is skipped, the rest are built, and the build then exits 1 with one Some templates failed to build: line on stderr naming every template it left unbuilt (a parent a target's chain failed on included).

isx branch

Create a new instance as a copy-on-write clone from a template or existing instance.

isx branch <name> [options]

isx shell

Open a shell in an existing instance.

isx shell <instance>

When the shell-status-bar feature is enabled, a two-line status bar is pinned at the bottom of the terminal showing the instance name, template, IP address, and network mode. Press F12 to open a quick-action menu with shortcuts from tool actions that set shell_menu: true. Enable with:

# ~/.config/incus-spawn/config.yaml
features:
  - shell-status-bar

isx run

Run the default action or a specific action on an instance.

isx run <instance> [options]

isx destroy

Destroy an instance, or bulk-destroy all templates or instances.

isx destroy <instance>
isx destroy --all-templates      # destroy all built templates (derived first)
isx destroy --all-instances      # destroy all instances

isx list

List the instances isx created, without opening the TUI. Templates are not listed: isx templates lists those. On macOS it starts the VM if it is stopped, except with -q, which shell completion runs. See Scripting isx for the plain and json formats.

isx list [options]

isx instances, which printed the names of every Incus instance not named tpl-*, is deprecated and will be removed in a later release; it now runs isx list -q. Shell completion scripts generated by this release no longer call it.

isx update-base

Check for and install base image updates.

isx update-base [<release-tag>] [options]

Pass a release tag (e.g. fedora-44-v2) to pin to that version.

isx update-all

Update system packages, npm globals, and git-fetch repos in all templates. Does not re-clone repos or reinstall tools; for that, use isx build.

isx update-all [options]

isx templates

Manage template definitions. Running bare isx templates defaults to list.

isx templates <subcommand>

isx templates list

isx templates list [options]

isx templates new

isx templates new [<name>]

isx templates edit

isx templates edit <name>

isx tools

List and inspect available tool definitions. Running bare isx tools defaults to list.

isx tools <subcommand>

isx tools list

isx tools list [options]

isx tools show

isx tools show <name>

isx account

Show or change which credential account an instance uses. Accounts themselves are configured with isx init. Running bare isx account defaults to list.

isx account <subcommand>

isx project

Manage project templates defined by an incus-spawn.yaml file.

isx project <subcommand>

isx project create

isx project create <name> [options]

A project name may be at most 52 characters, since it is built as <name>-rebuilding first. Re-creating an existing template builds the new one alongside it and replaces it only once the build succeeds. If a repository fails to clone or the pre-build fails, the command exits non-zero, deletes the incomplete build and keeps the previous template.

isx project update

isx project update <name> [options]

If any step fails (system update, npm update, git fetch, pre-build), the command exits non-zero and the template is kept.

isx proxy

Manage the MITM authentication proxy.

isx proxy <subcommand>

isx proxy start

isx proxy start [options]

isx proxy dump

isx proxy dump [options]

isx doctor

Diagnose host, proxy, VM, and tunnel health; offers to fix problems found.

isx doctor [options]

Findings are marked ✓ healthy, ⚠ worth a look, ✗ broken, or · for a note. Notes don't affect the exit code.

--bundle creates an archive to attach to a GitHub issue. Credentials are redacted before anything is written, and REDACTIONS.txt in the archive lists what was removed.

isx clean

Remove cached data, state, or configuration.

isx clean <subcommand> [options]

All subcommands accept these options:

isx reset

Return isx to a freshly installed state. Removes all instances and templates, cached images and downloads, the proxy service, the VM (macOS) and all configuration, including SSH keys and the CA certificate. It shows what will be removed and asks first. Run isx init afterwards to set up again.

isx reset

isx vm

Manage the incus-spawn VM appliance. macOS only.

isx vm <subcommand>

isx vm restart

isx vm restart [options]

Stops and restarts the VM, applying any pending appliance updates. Running containers will be stopped.

isx vm resize

isx vm resize <size>

Size must be larger than the current disk (grow-only), e.g. 100G.

isx vm reset

isx vm reset [options]

Wipes the VM's storage pool, for when it's beyond repair (for example, orphaned subvolumes reported by isx doctor). Every instance, template and cached image is deleted; isx lists them and asks first, or needs --yes without a terminal. Rebuild your templates afterwards with isx build --all.

isx ask

AI-powered help. Ask any question about incus-spawn (uses AI tokens).

isx ask <question...>

isx mcp

Serve isx to an agent on this machine over the Model Context Protocol (stdio). Started by the agent, not by hand:

claude mcp add isx -- isx mcp

See Delegating from an agent on your host for what it offers and how to approve templates.

isx mcp --caller-instance <name> serves an instance branched with --mcp-client instead; the proxy runs it for each connection that instance makes to https://mcp.isx.internal/mcp (a coordinator in an instance).

isx completion

Print a shell completion script.

isx completion [<shell>]

Supported shells: bash (default), zsh, fish.

The scripts also complete <namespace>=<account> for isx branch --account and isx account set, and the namespaces for isx account unset. They read account names from isx account list --completion, which prints names only, never credentials.

Scripting isx

Query commands take --format=table|plain|json: isx list, isx templates [list], isx tools list, isx tools show, isx account list, isx account show, isx proxy status, isx proxy activity, isx doctor, isx vm status (macOS), isx update-base --list and isx branch.

• table is for people. It may change in any release, so don't parse it.
• plain prints one record per line, its fields tab-separated, with - for an empty field. There is no header, padding, colour or glyph, and no results means no output.
• Neither format lets a value write a control character to your terminal. A value can hold one: an instance stamp set by hand with incus config set, say, escape sequence and all. plain keeps each record on one line and safe to print, so every control character in a value becomes a space: the C0 controls U+0000 to U+001F (tab, line feed, carriage return, backspace, form feed and ESC among them), DEL, the 8-bit controls U+0080 to U+009F, U+2028/U+2029, and the bidirectional embeddings, overrides and isolates U+202A to U+202E and U+2066 to U+2069, which would make your terminal show the rest of the line out of order. That loses them, so read json when you need a value exactly: it keeps every value as it is, writing each of those characters as a JSON escape that any JSON parser turns back into the original: \t, \n, \r, \b and \f for tab, line feed, carriage return, backspace and form feed, and \uXXXX for every other one.
• json prints an array of objects, or one object for a command about one thing (tools show, proxy status, vm status, branch). A list value is an array in json and its elements joined by , in plain. An absent value is null, and sizes are in bytes. Times are ISO-8601 with their offset: 2026-10-05T12:34:56+02:00, or 2026-10-05T12:34:56Z on a host whose zone is UTC, so match both forms. Instances stamped by older isx releases recorded only a date, which prints as an ISO-8601 date (2026-09-01). A time isx cannot read is null (- in plain).
• When isx cannot read what Incus answered, the command fails (exit 1, the reason on stderr). It never prints an empty result.
• Both plain and json are stable. Fields may be added at the end, but are never renamed, removed or reordered.
• Results go to stdout. Errors and diagnostics go to stderr, so stdout holds only results. Commands that act (build, branch, destroy, ...) report their steps on stdout and their warnings and notes on stderr. A status command's report is its result in every state: isx proxy status prints it on stdout whether or not the proxy is healthy, and the exit code says which.
• isx writes colour, clickable links and animated progress only when stdout is a terminal. When stdout is redirected or piped, or NO_COLOR is set to a non-empty value, neither stdout nor stderr holds escape sequences. isx cannot tell whether stderr alone is a terminal, so isx build tpl-minimal 2>build.log run from a terminal still colours the warnings in build.log. For a clean log, redirect both streams or set NO_COLOR=1.

isx list prints name, status (running, stopped, ...), ipv4, parent, runtime (container or virtual-machine), created, mcp_state and mcp_purpose, in that order. The last two are null (-) unless an isx mcp session made the instance. mcp_state is then held (a session holds it), orphaned (its session ended and nobody has adopted it yet) or kept (an agent handed it to you with keep_instance), and mcp_purpose is what the agent said the instance is for, or null. For names alone, use isx list -q:

for name in $(isx list -q --status=stopped); do isx destroy "$name" --skip-confirmation; done
isx list --format=json | jq -r '.[] | select(.parent == "tpl-java") | .name'

The fields of the other commands, in order:

Exit codes: