eosctl: the command line tool¶

eosctl is a command line client for the same HTTP API the Eight.ly OS dashboard uses. It is generated directly from the API's own OpenAPI spec (see API Reference), so every command maps to a real endpoint and the tool cannot drift out of sync with the API — when the API changes, eosctl is regenerated from the new spec.

Getting it¶

When it is published it is a single program with nothing else to install. Check that it runs:

eosctl --version

Pointing it at a box and signing in¶

eosctl talks to http://localhost:8080 by default. Point it at a real box and give it a credential:

export EOS_BASE_URL="http://box.example.lan:8080"
export EOS_BEARER_AUTH="eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Or save the token to disk instead of exporting it every session:

eosctl auth set-token eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That writes the config file at ~/.config/eosctl/config.toml (base_url and the bearer credential can also be set directly in that file). Get the key itself from the dashboard — see API Keys for creating one.

Check the setup:

eosctl doctor

doctor reports the base URL, whether a credential is configured, whether the API answers, and the state of eosctl's local SQLite cache. Run it with --json for a machine-readable version.

Output formats¶

The same command can return a human table, JSON, CSV, or plain tab-separated text:

eosctl containers list                          # table in a terminal, JSON when piped
eosctl containers list --json                    # JSON
eosctl containers list --csv                      # CSV
eosctl containers list --plain                    # tab-separated
eosctl containers list --json --select id,name,status   # only these fields
eosctl containers list --dry-run                  # show the request, send nothing
eosctl --agent containers list                    # --json --compact --no-input --no-color --yes, in one flag

--agent is the flag to reach for when scripting or driving eosctl from another program — it turns off prompts and coloring and asks for compact JSON in one shot.

A dry run shows the exact request without sending it:

$ eosctl containers list --dry-run
GET http://localhost:8080/api/containers

(dry run - no request sent)

A tour of the command groups¶

eosctl --help lists every top-level command group. Beyond scripting shortcuts (doctor, sync, search, profile, which, api, agent-context, …), the groups that map onto the product are:

activity   auth       authz    backup    containers   edition
files      ha         lxc      nova      proxy         shares
storage    stream     system   tasks     traefik       updates
ups        vm

Each group has its own subcommands and its own --help:

eosctl vm --help
eosctl storage --help
eosctl backup --help

eosctl api lists every endpoint by its raw interface name (70 interfaces measured against today's build) for callers that need full coverage beyond the friendly top-level groups above. eosctl which "<what you're trying to do>" resolves a plain-English request to the closest matching command.

Containers¶

eosctl containers list
eosctl containers get 550e8400-e29b-41d4-a716-446655440000
eosctl containers action 550e8400-e29b-41d4-a716-446655440000 --action start
eosctl containers metrics

eosctl containers groups: action (start/stop/restart, takes the container ID as a positional argument plus --action), get (ID as a positional argument), list, metrics, shell-get.

Virtual machines¶

eosctl vm list
eosctl vm create --name my-vm --vcpus 2 --memory-mb 4096 --disk-size-gb 40 --iso ubuntu.iso
eosctl vm get 550e8400-e29b-41d4-a716-446655440000

eosctl vm create takes --name, --vcpus, --memory-mb, --disk-size-gb, --iso, --net-bridge, --net-model, --storage-pool, --bios, --machine, --cpu-type, PCI/USB passthrough flags, and --cloudinit-* flags for unattended provisioning. eosctl vm also covers images, isos, isos-upload, templates, hostdev-claims, and tasks.

LXC containers¶

eosctl lxc list
eosctl lxc create --name my-container --distribution debian --release trixie
eosctl lxc install-app --name jellyfin-lxc --app jellyfin --cpu 2 --ram 2048 --disk 20

eosctl lxc create takes --name, --distribution, --release, --arch, --bridge, --rootfs-size, --template, --variant, or --stdin to read a full request body as JSON. eosctl lxc install-app takes --name, --app, --cpu, --ram, --disk, --net, --bridge, --gpu, --start-on-boot.

Storage¶

eosctl storage status
eosctl storage snapraid-status
eosctl storage cache-status
eosctl storage health

eosctl storage is the largest group — array management (array-create, array-adopt, array-start/stop, array-disk-add/remove/replace/evacuate), the Shelver (cache-mover-status, cache-mover-trigger, cache-policy), SnapRAID (snapraid-sync, snapraid-scrub, snapraid-check), disk operations (disks, disks-prepare, disks-wipe, smart), and ZFS pools.

Backup¶

eosctl backup jobs
eosctl backup storage

eosctl backup covers job CRUD (jobs-get, jobs-post, jobs-update, jobs-delete), appdata-restore, and remote storage target testing (storage-test).

Nova¶

eosctl nova health
eosctl nova models
eosctl nova chat --message "how much disk space is free?"

eosctl nova also covers catalog, recommend (best-fit model for this hardware), chats/post-chats (conversation history), memory, and engines-status/engines-restart.

System, health, and node¶

eosctl system info
eosctl system version
eosctl system logs
eosctl health overview

eosctl system also has gpu/gpu-assign (GPU passthrough), sensors, parity-check, and update/backup commands.

Shares¶

eosctl shares shares
eosctl shares users
eosctl shares status

eosctl shares manages Samba shared folders: shares/shares-get/shares-update/ shares-delete, users, config, start/stop/restart/reload, and logs.

Sample answer shape¶

Read commands that go through the local cache or the live API wrap their answer in a small envelope:

{
  "meta": { "source": "live" },
  "results": { ... }
}

meta.source is "live" when the answer came straight from the API, or "local" when it came from eosctl's offline SQLite store (populated by eosctl sync). Parse .results for the data itself.

Exit codes¶

Known limitations¶

• Not published for download yet (see the top of this page).
• eosctl auth setup does not open a page for you: get the key from the dashboard's API Keys screen (see API Keys) and give it to eosctl auth set-token.
• Signing out of the dashboard currently stops that account's API keys working too. If eosctl is suddenly refused, make a new key. This is being fixed.
• eosctl-mcp, the MCP server built from the same code, is a separate binary — see The MCP server.