CLI Commands

aurum is the released command interface for project creation, local execution, installation, Forge delivery, and lifecycle operations. Repository-only service-stack commands appear in the generated inventory but are not part of the installed product workflow documented here.

The command-name tables below are generated from the CLI dispatch. Option details are maintained against the command definitions and validated by the documentation build.

Top-level commands

Command	Description
info	Show CLI/runtime information or project information.
create	scaffold a new project from template
version	Print the Aurum CLI version.
help	Show Aurum CLI help.
compile	Compile a project directory.
install	Install a project locally (alias for aurum push local).
run	Run a project (local directory or installed instance).
stop	Stop an installed project.
status	Show control-plane summary or project status.
list	List installed projects.
up	Start a local Aurum service stack.
down	Stop a local Aurum service stack.
remove	Remove an installed project.
logs	Show project logs.
push	push source to a remote server and register the version

aurum daemon subcommands

Subcommand	Description
install	Install the aurumd systemd user unit.
status	Show daemon systemd and RPC status.
start	Start the daemon.
stop	Stop the daemon.
restart	Restart the daemon.
enable	Enable the daemon unit.
disable	Disable the daemon unit.
logs	Show daemon logs.

aurum remote subcommands

Subcommand	Description
add	register a remote server
list	list registered remotes
remove	remove a registered remote
show	show remote details

Runtime control commands

These act on a running project (pause / resume apply to REPLAY projects, freeze / unfreeze to LIVE projects).

Command	Description
pause	Pause a REPLAY project.
resume	Resume a REPLAY project.
freeze	Freeze a LIVE project.
unfreeze	Unfreeze a LIVE project.

Shell completion

aurum completion prints a completion script for the requested shell.

Shell	Description
bash	Generate bash completion script
zsh	Generate zsh completion script

Global option

--home <path> selects the Aurum home for the command. Resolution order is the option, AURUM_HOME, then ~/.aurum.

Project creation and compilation

aurum create <name> creates CMakeLists.txt, main.cpp, and config.hpp in a new directory.

aurum compile <dir> compiles one project without starting it.

Option	Meaning
--target <name>	Override the target resolved from aurum_project.
--build-dir <path>	Use an explicit project build directory.
--no-build	Resolve an existing executable without invoking CMake.
--no-cache	Discard the Aurum-managed CMake cache before compiling.

Local run

aurum run [project] has two modes. A directory runs that source project in the foreground. An installed project name asks aurumd to start the registered instance. The default project argument is the current directory.

Option	Meaning
--target <name>	Override the CMake target in directory mode.
--build-dir <path>	Set the build directory in directory mode.
--no-build	Run an existing executable in directory mode.
--no-cache	Clear the managed compile cache first.
--log <level>	Foreground level: trace, debug, info, warn, error, or fatal.
--journal	Enable the local journal for the foreground run.
--auth <ref>	Select a credential document for startup.
--version <version>	Select an installed version.
--server <remote>	Run the installed project on a registered Forge target.
--wait	Wait for process-state convergence.
--timeout-ms <n>	Bound the convergence wait; default 30000.
-- <args...>	Forward remaining arguments to a foreground project executable.

Install and remove

aurum install [dir] compiles and registers a version in the selected Aurum home. It accepts the compile options above plus:

Option	Meaning
-f, --force	Replace an existing local registration without prompting.
--ephemeral	Mark the installed instance for retention after completion.
--ttl-seconds <n>	Retention for an ephemeral instance; default 86400.

Source archive and instance identity options used by remote delivery are not a normal interactive install interface.

aurum remove [remote] <project> removes a stopped installed version.

• --version <version> selects one version when several exist.

• --server <remote> routes the command over SSH; do not combine it with a positional remote.

• -f, --force skips confirmation but does not remove a running instance.

Forge delivery and remotes

aurum push [project] [remote] packages the project source, checks that its declared version does not already exist, transfers it over SSH, and registers it on the target. With no operands it uses the current directory and default remote.

aurum remote add prod aurum@forge.example.com --default
aurum push ./signal-watch prod

Remote registry commands:

Command	Meaning
aurum remote add <name> <user@host[:port]> [--default]	Register an SSH target.
aurum remote list [--json]	List registered targets.
aurum remote show <name> [--json]	Show one target and its reachable project inventory.
aurum remote remove <name>	Remove the local registry entry.

Remote names begin with a lowercase letter and contain only lowercase letters, digits, and hyphens. The registry is $AURUM_HOME/remotes.toml. SSH host keys, user keys, and any proxy route come from the normal SSH environment.

Inventory and lifecycle

Command	Meaning
aurum list [--server <remote>] [--json]	List installed instances.
aurum status [project]	Show the inventory or one project’s synthesized state.
aurum info [project]	Show CLI/runtime configuration or delegate to project status.
aurum stop <project>	Request graceful stop.
aurum logs <project>	Read project output.

status accepts --version, --server, and --json. stop accepts --version, --server, --wait, and --timeout-ms.

Project log options are:

• --tail follows the log;

• --journal reads the managed service journal;

• --version and --server select the instance;

• --json requests machine-readable output where supported.

Project logs do not use -f. That short option belongs only to daemon logs.

Runtime controls

pause and resume apply to installed REPLAY instances. freeze and unfreeze apply to installed LIVE instances. Each command takes a project and optional --version. These controls act on the selected local Aurum home; they do not expose --server.

Daemon

aurum daemon manages the released per-user aurumd service:

Command	Meaning
daemon install	Install or update the user service definition.
daemon status	Show service and RPC reachability.
daemon start|stop|restart	Change current service state.
daemon enable|disable [--now]	Change login-time activation, optionally current state too.
daemon logs [-f|--follow]	Read daemon logs, optionally following them.

daemon install accepts --binary, --reconcile-policy (observe or enforce), --store-backend (file or sqlite), --http-host, --port, --advertise-host, and --now.

Completion and version

aurum completion bash and aurum completion zsh print a shell completion script. aurum version prints the installed CLI version and aurum help prints command help.