#Conventions
Every command in this book follows the rules on this page: how a line is spelled, which options are global, what the JSON payload looks like, which exit code means what, where each kind of output goes, and how a write is recorded. If you read one page before using the rest of the book, read this one.
#Spelling and order
aegis <command> [<action>] [options].--path /srv/site and --path=/srv/site arethe same to the parser.
-h and --help work on the top-level command and on every group andaction built with argparse. The verbs under aegis account build their own small parsers without a help flag; aegis account help prints the usage line instead, and the account page lists the verbs.
--to, --arg, …) accumulates. A repeatedscalar option keeps the last value given.
aegis --json status is valid,aegis status --json is a usage error, because status has no --json.
ai, cubes nginx config) printsits command list when called without an action. A group built on plain subparsers (sys, docs, tasker, or a cube itself) requires one and exits 2 otherwise.
#Global options
| Option | Default | Effect |
|---|---|---|
--json | off | print one JSON object on stdout instead of the human report |
-h, --help | — | print the usage line and options, exit 0 |
Two command-level options are easy to mistake for global ones:
install and configure accept -v, --verbose and --v to print a lineper step instead of a progress bar.
account accepts --json anywhere on its own line, and ai prompt has a--json that prints the final answer instead of streaming it. Both switch on the same machinery as the global flag.
#JSON output
--json replaces the human output with one JSON object on stdout, one line, ending with a newline. Every payload starts with ok:
aegis --json cubes list"ok": true "cubes": "bind" "certbot" "nginx"aegis --json cubes nginx config get workers"ok": true "cube": "nginx" "result": "workers=auto"aegis --json cubes nginx config get nope"ok": false "cube": "nginx" "error": "unknown setting: nope"| Key | When | Meaning |
|---|---|---|
ok | always | true when the command did what was asked |
error | on failure | one sentence, the same text a human would read |
command | most write commands | the operation, e.g. account.sites.create |
cube | cube commands | the application the result belongs to |
result | cube commands | one-line value: a setting, a path, a count |
Other keys are the data that command reports, under the name the command page documents.
A report payload carries the whole snapshot. aegis --json status prints the following object as a single line; it is indented here so the fields can be read:
{ "ok": true, "keeper": {"pid": 731254, "state": "running (pid 731254)", "uptime": "3h 12m", "boot": true}, "services": [{"service": "tasker", "state": "running", "pid": "731401", "uptime": "3h 12m"}], "jobs": [{"job": "geoip-refresh", "every": "6h", "last": "2026-11-17 06:00:04", "next": "2026-11-17 12:00:04", "result": "ok"}], "panel": {"state": "running (pid 731900)", "pid": "731900", "port": "9981", "uptime": "3h 11m"}}Four rules make that reliable in a script:
ok orthe status without parsing text;
--json — aegis sys and aegis docs do not have one;
stderr (account does). Read stdout and check ok rather than assuming stderr is empty.
#Exit codes
| Code | Meaning |
|---|---|
0 | the command did what was asked |
1 | it ran and something failed: a health check, a refused path, a failed step |
2 | the line was wrong: unknown command, missing argument, nothing asked for |
130 | interrupted with Ctrl+C |
A usage error (unknown command or subcommand, missing required option) is exit 2 with the usage message on stderr. The wording of that message is argparse's, so it is not reproduced here. sys perms also returns 2 when no operation was requested, because the line is incomplete rather than failed.
Ctrl+C is 130: the dispatcher prints cancelled and returns 130. A command that owns the interrupt is the exception — docs web stops its server, prints stopped, and exits 0.
#Streams
| Output | Stream |
|---|---|
| results, tables, reports | stdout |
info and success lines | stdout |
warning and error lines | stderr |
| spinners, progress bars, timelines | stderr |
| JSON payloads | stdout |
The split is what makes aegis status > state.txt keep the report in the file while a warning about a dead service still reaches the terminal. Diagnostics are complete lines: the marker carries the colour, the text stays plain, so a line copied out of a terminal has no escape codes in the middle of it.
#Colour, symbols and NO_COLOR
| Setting | Effect |
|---|---|
| output is a terminal | colour on |
| output is a pipe or a file | colour off |
NO_COLOR=1 | colour off, even on a terminal |
FORCE_COLOR=1 | colour on, even through a pipe |
TERM=dumb | colour off |
The flags accept 1, true, yes and on as true. NO_COLOR=0 (or false, no, off, empty) does not disable colour; FORCE_COLOR=0 turns it off even on a terminal. NO_COLOR is checked first, so it wins over FORCE_COLOR.
Symbols follow the stream encoding, not the settings: with UTF-8 you get ✔, ✖, ⚠, ℹ and table rules drawn with ─; without it the same lines use OK, X, !, i and -. Progress bars and timelines switch from █░ and ●○ to #- the same way.
Animation is tied to the terminal, not to colour: with NO_COLOR set, the spinner and the progress bar still redraw, they just lose their colour.
#Live lines
Three components draw in place while work runs: the spinner (unknown duration), the progress bar (known count) and the timeline (one dot per item of a batch). Each occupies exactly one terminal line, writes to stderr, and is silent when stderr is not a terminal. Before any message is printed they are erased, so a warning never lands in the middle of a bar.
One frame of each:
⠹ Installing nginxInstalling applications [██████████░░░░░░░░░░░░░░░░░░░░] 33% 5/15Downloading apps [●●●●●○○○○○○○○○○○] 5/18 mariadb 13.0.2The bar shrinks itself to the terminal width — the label is truncated first and the counter is dropped only on a genuinely tiny terminal, because a line that wraps would be overwritten on the wrong row. The timeline fits its label and its note into the width the same way.
install and configure choose between the bar and plain step lines: the bar only when stdout is a terminal and -v was not given, plain lines otherwise. Either way the last line of a run is a message, so a log always ends with an outcome.
#Every write is a task
The panel does not perform a write inside the request that asked for it. It validates the form, stores a task, and the tasker daemon runs it; the row and its log stay behind, which is why a change made in the panel can be read back later with aegis tasker list and aegis tasker show.
The command line has both doors. Most commands run their work in the foreground and show it: aegis sys perms executes the setfacl calls in front of you and prints each one. The same operation is also registered as a task action, sys.perms.apply, so it can be queued when the write needs a task row:
aegis tasker run internal sys.perms.apply --arg path=/home/john/www --arg mode=fix --wait✔ task 118 queueddone: 6 change(s) on /home/john/wwwThe task records every command as a step, and the actor: cli for a task started from the shell, the panel username for one started from a form. That is the point of the model — a change that mattered leaves a readable trace, not a line that scrolled past.
See tasker for the queue itself: the four types, steps, rollback, retries, and what a failed task keeps.