#The CLI Book
aegis is the command line of the Aegis hosting platform: one program with subcommands for everything the platform does. It installs applications, builds their sources, supervises their daemons, creates mail domains, issues certificates, and renders this manual. The panel performs most of its writes through the same code, so what you type and what the panel does cannot drift apart.
This book is the reference for that command line. Each command page covers one group; every command on it has a description, its syntax, a table of the options and their defaults, copy-paste examples, and the output the command prints. It is written for an operator who knows Linux but not this codebase: no knowledge of the Python modules is assumed.
#Running a command
./bin/aegis status # from a checkout/bin/aegis status # installed host: the link the installer madeaegis --json status # global options go before the commandbin/aegis resolves its own location, including through a symlink, changes to the project root, and runs the bundled interpreter at runtime/python/current/bin/python3 with -E -s. The host's PYTHONPATH and user site-packages therefore cannot change what a command sees. If the runtime is missing the launcher says so and exits 1; bin/aegis thor runtime prepare builds it.
Commands that install, configure or change permissions work on the host itself and are meant to run as root. Read the page of a command before running it as another account.
#How the commands are organised
| Layer | Spelling | Examples |
|---|---|---|
| install phases | aegis <command> | install, setup, configure, build |
| reports | aegis <command> | status, check, restart |
| module groups | aegis <group> <action> | aegis keeper restart |
| cubes | aegis cubes <app> <action> | aegis cubes nginx reload |
A group is a module with its own set of actions; a cube is one installed application (nginx, php, postfix, …) reached through aegis cubes. Cube actions are mounted from the cube's own directory, so --help on a cube lists exactly what that application supports.
Groups built on the shared group helper print their own command list when called without an action: aegis ai, aegis cubes nginx config. Every cube also answers help with its commands and examples, and aegis cubes help does the same for all of them. Groups built on plain subparsers (sys, docs, tasker, or a cube itself) require an action and answer a usage error with exit code 2; use --help there.
#How to read a page
Every command entry has the same parts:
Commands or options that change the host irreversibly are marked Destructive. in bold. Nothing else on a page is a warning of that weight.
The rules that hold for every command — global options, JSON payloads, exit codes, streams, colour and the task model — are on Conventions and are not repeated on each page.
#How aegis --help maps onto the book
aegis with no arguments prints the command list and exits 0, and the same page answers aegis help, aegis -h and aegis help <command>. The order is the one the parser mounts, which follows the work: what a new host runs first, then daily operation, the hosting surface and the platform below.
aegis Hosting platform controlCommands install Prepare the host: setup questions, checks and builds setup Ask the install questions and write server.toml build Compile and publish the Rust applications configure Write application configuration and start the services status Keeper, services and scheduled jobs at a glance check Health check, with the command that fixes each problem restart Restart the keeper, the supervised services and the panel account Create, inspect and retire hosting accounts web nginx vhosts, PHP configuration and the web database db Databases, migrations and seeders ssl Local certificates for the services geoip Download and inspect MaxMind databases keeper Supervise the platform daemons collector Collect and store platform counters pulse Realtime monitor feeding the WebSocket transport tasker Run and inspect tasks cubes Configure and reload the installed applications thor Application sources and the bundled Python runtime ai AI providers, models, agents and chats sys File permissions for accounts and the web user web-admin Run and inspect the Aegis panel docs Build the HTML documentation, or serve it create Pack this checkout into an installable archive publish Link the launcher so `aegis` works everywhereRun 'aegis <command> --help' for the options of one command.#Building an installer
aegis create packs this checkout into one archive a fresh host can unpack: the code, the bundled runtime, the migrations and the shipped configuration. It writes storage/app/install/aegis-<major>-<minor>.tar.gz and keeps only that file — the previous archive is removed.
The version is a counter, not a date: the minor goes 1..30, then the major steps and the minor starts again at 01 (1-30 is followed by 2-01). The counter lives in storage/app/install/version.json, next to the archive it named, so it survives the file being replaced.
aegis createaegis --json create aegis create aegis 1.02 187.2 MB /etc/aegis/storage/app/install/aegis-1-02.tar.gzThe installer page is not a server of its own: the panel serves it at /installer, together with /docs. That page has no authentication on purpose — a fresh host has no account yet, and the whole point is copying one command from another machine.
| route | serves |
|---|---|
/installer | the instructions, with the install line to copy |
/installer/install | the bash installer from the checkout root |
/installer/download/<file> | one archive, by file name |
/installer/files.json | the archive list |
The browser address becomes the host a remote machine downloads from, so open the page on the address that machine can reach.
The host pipes the script into bash. The panel fills the download address into it at serve time, so no argument is needed — the archive comes from the same host the script came from. The script extracts into /etc/aegis and stops there, printing the command that continues in a real terminal:
cd /etc/aegis; ./bin/aegis installIt does not start the install by itself: a script piped from the network has no reliable stdin, and the setup asks questions.
#Linking the launcher
The installer links the launcher once, as its bin-link task, so a host that ran the full install answers to aegis from any directory. After a reinstall, or on a host where the link was removed, publish creates it again:
aegis publish # /bin/aegis -> <checkout>/bin/aegisaegis publish --path /usr/local/bin/aegisaegis --json publishIt is idempotent: a link that already points at this checkout is reported and nothing is written. A file or link pointing somewhere else is never replaced — the command refuses and exits 1.
aegis publish /bin/aegis -> /etc/aegis/bin/aegis--help on a command or group prints its usage line, its options and argparse's help text for each one (the per-account verbs under account are the exception: they build their own parsers). That is enough to recall a flag; it is not enough to know what the flag changes, what the command prints, or which exit code it returns. The book adds exactly those:
| What you need | Where to find it |
|---|---|
| the command list | aegis, or the contents below |
| flags and defaults | aegis <command> --help and its options table |
| what a flag changes | the options table and the mode tables on its page |
| what it prints | the output blocks on its page |
| what a script may rely on | Conventions |
Two habits keep the line unambiguous: put global options before the command (aegis --json status), and put an action before its options (aegis sys perms --path /srv/site --check).
#Contents
#Start here
colour, live lines, the task model.
#Install and operate
#The platform
#Intelligence
#Cubes
One page per application: nginx, php, bind, certbot, mail, postfix, dovecot, opendkim, postsrsd, postgresql, mariadb, redis, beanstalkd, vsftpd, supervisor, and composer, git, ffmpeg.
The root-level commands (install, setup, configure, build, status, check, restart) are a sequence rather than a group; the manual's Command line page is the short reference for them.
#Where the book lives
The sources are docs/cli-book/*.md. The sidebar order is written by hand in app/modules/docs/book.py, one Page per document, because the order a reader follows is not the order of the file names. aegis docs build renders the book as its own site under public/docs/cli-book/, and an installed panel serves it at /docs/cli-book/. A page whose source file is missing is skipped by the builder rather than rendered empty.