Aegis documentation

#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

  • A command is aegis <command> [<action>] [options].
  • Options come after their action. --path /srv/site and --path=/srv/site are
  • the same to the parser.

  • -h and --help work on the top-level command and on every group and
  • action 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.

  • A flag documented as repeatable (--to, --arg, …) accumulates. A repeated
  • scalar option keeps the last value given.

  • Global options go before the command: aegis --json status is valid,
  • aegis status --json is a usage error, because status has no --json.

  • A group built on the shared group helper (ai, cubes nginx config) prints
  • its 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

    OptionDefaultEffect
    --jsonoffprint 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 line
  • per 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:

    bash
    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"
    KeyWhenMeaning
    okalwaystrue when the command did what was asked
    erroron failureone sentence, the same text a human would read
    commandmost write commandsthe operation, e.g. account.sites.create
    cubecube commandsthe application the result belongs to
    resultcube commandsone-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:

    text
    {  "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:

  • the object is the whole of stdout: nothing else is printed there;
  • the exit code keeps its meaning (see below), so a caller can check ok or
  • the status without parsing text;

  • a group that does not implement a payload prints its human lines even with
  • --json — aegis sys and aegis docs do not have one;

  • when a group reports a failure it may also print the human diagnostic to
  • stderr (account does). Read stdout and check ok rather than assuming stderr is empty.

    #Exit codes

    CodeMeaning
    0the command did what was asked
    1it ran and something failed: a health check, a refused path, a failed step
    2the line was wrong: unknown command, missing argument, nothing asked for
    130interrupted 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

    OutputStream
    results, tables, reportsstdout
    info and success linesstdout
    warning and error linesstderr
    spinners, progress bars, timelinesstderr
    JSON payloadsstdout

    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

    SettingEffect
    output is a terminalcolour on
    output is a pipe or a filecolour off
    NO_COLOR=1colour off, even on a terminal
    FORCE_COLOR=1colour on, even through a pipe
    TERM=dumbcolour 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:

    text
    ⠹ Installing nginxInstalling applications  [██████████░░░░░░░░░░░░░░░░░░░░]   33%  5/15Downloading apps  [●●●●●○○○○○○○○○○○]  5/18  mariadb 13.0.2

    The 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:

    bash
    aegis tasker run internal sys.perms.apply     --arg path=/home/john/www --arg mode=fix --wait
    text
    ✔ task 118 queueddone: 6 change(s) on /home/john/www

    The 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.