Updates and the aseStack CLI¶

The installer adds a local command for routine controller operations. The guaranteed command name is asestack. It also installs the shorter ase alias when that name is not already used by another program.

The examples on this page use ase. Substitute asestack if the short alias is not available.

Update the controller¶

Check the running and available versions before starting:

sudo ase version
sudo ase health
sudo ase status

Then run the interactive updater:

sudo ase update

The updater:

downloads the current quick-start installer and its SHA-256 checksum;
verifies the installer checksum;
compares the running version with the available version;
asks for confirmation when an update is available; and
runs the verified installer.

The installer creates a control-plane backup before replacing an existing installation, preserves /etc/asestack/asestack.env, installs the new files, restarts the controller, enables the backup timer, and refreshes the local agent when automatic local-agent setup is enabled. Do not set ASESTACK_SKIP_PRE_UPGRADE_BACKUP=true unless you have deliberately made and verified another backup.

For unattended maintenance, confirmation must be explicit:

sudo ASESTACK_UPDATE_CONFIRM=yes ase update

After the update, verify both the local endpoint and the public origin:

sudo ase health
sudo ase status
sudo ase version
curl -fsS https://control.example.com/api/v1/health

The local health result is the authoritative on-host check. A public failure with a healthy local endpoint usually points to DNS, TLS, or reverse-proxy configuration. See Troubleshooting.

Warning

The updater does not promise an automatic application rollback. Keep the pre-upgrade backup, confirm that it contains the expected state, and follow the backup and restore guide if recovery is required.

Update a managed-server agent¶

The controller update and a managed host's agent update are separate. Run the agent-only updater on the managed host when the Servers workspace reports version drift:

curl -fsSL https://cdn.asestack.dev/update-agent.sh | sudo bash
sudo systemctl status asestack-agent

The Servers workspace also provides a host-specific Copy update command. Use that command when a host has a customized agent path or updater URL.

Command reference¶

Run ase help for the command list and ase help <command> for command-specific usage.

Command	Purpose	Important behavior
`ase backup-provider-check`	Check optional WebDAV, Google Drive, Dropbox, OneDrive, and SFTP validation inputs.	Read-only; it reports missing variable names and never prints credential values.
`ase doctor`	Inspect the local aseStack agent and host.	Runs the installed agent doctor command.
`ase deployment-cleanup`	Summarize generated deployment-check rows and retained packet files.	Summary is non-destructive. The `cleanup` action is destructive and separately guarded.
`ase evidence-policy`	Check local deployment-evidence retention and off-host policy.	Reports retention, packet coverage, and configured off-host target.
`ase evidence-sync`	Check, preview, or upload evidence to Cloudflare R2.	Upload and lifecycle changes require credentials; lifecycle application has an explicit confirmation guard.
`ase health`	Query the direct local `/api/v1/health` endpoint.	Reads `ASESTACK_ADDR` from the runtime environment file when present.
`ase logs`	Follow controller and local-agent journals.	Equivalent to following both `asestack.service` and `asestack-agent.service`.
`ase logs-app`	Follow the controller journal.	Uses `journalctl` for `asestack.service`.
`ase logs-agent`	Follow the local-agent journal.	Uses `journalctl` for `asestack-agent.service`.
`ase logs-vi`	Follow control-panel visitor access logs.	Reads the configured Nginx access log.
`ase logs-ips`	Count visitor IP addresses in the access log.	Requires permission to read the access log.
`ase passkey-check [URL]`	Check production passkey prerequisites.	Automated preflight only; a real browser and authenticator are still required.
`ase release-check`	Run the packaged release-candidate checks.	The default checks are read-only when inputs are available. Deployment validation and evidence upload are opt-in.
`ase repair`	Reapply service units, permissions, CLI helpers, backup timer, and local-agent wiring.	Does not replace `/opt/asestack` or overwrite `/etc/asestack/asestack.env`.
`ase restart`	Restart the controller and local-agent services.	Requires systemd privileges.
`ase status`	Show controller, agent, and backup-timer status.	Displays `asestack.service`, `asestack-agent.service`, and `asestack-backup.timer`.
`ase update`	Update from the configured CDN release channel.	Verifies the downloaded installer and asks for confirmation.
`ase verify-operator-history`	Verify a signed operator-history archive offline.	Validates metadata, digest, and HMAC signature without extracting the archive.
`ase version`	Show the running and available versions.	Reads the running version from local health and the available version from the latest installer.

Convenience flags are also available:

ase -v
ase -l
ase -l app
ase -l agent
ase -l vi
ase -l ips

Common maintenance commands¶

Inspect services and logs¶

sudo ase status
sudo ase health
sudo ase logs

Use a more focused log command when diagnosing one component:

sudo ase logs-app
sudo ase logs-agent
sudo ase logs-vi

Repair local service wiring¶

Use repair when an upgrade or manual host change has damaged unit files, ownership, helper symlinks, the backup timer, or local-agent wiring:

sudo ase repair

By default repair restarts services, repairs the local agent automatically when applicable, and does not run the smoke check. The following switches change that behavior:

sudo ASESTACK_REPAIR_RESTART=false ase repair
sudo ASESTACK_REPAIR_LOCAL_AGENT=false ase repair
sudo ASESTACK_REPAIR_SMOKE_CHECK=true ase repair

Repair is not a data restore and does not replace application files. Use the backup and restore guide for lost or damaged state.

Check passkey readiness¶

sudo ase passkey-check https://control.example.com

When the controller uses a security entrance, provide the full entrance URL at the terminal without recording it in documentation, tickets, or shell-history exports. The checker uses an isolated cookie jar and its sanitized summary does not include the entrance path.

The checker requires Turnstile by default. If the controller intentionally does not use Turnstile, match the deployed policy explicitly:

sudo ASESTACK_PASSKEY_CHECK_REQUIRE_TURNSTILE=false \
  ase passkey-check https://control.example.com

See Security for the required browser-device test.

Verify an operator-history archive¶

On the controller, the verifier reads the backup credential key from the runtime environment by default:

ase verify-operator-history ./operator-history.tar.gz

For offline verification on another trusted machine, use a protected key file:

ase verify-operator-history \
  --key-file ./operator-history-verification.key \
  --summary-file ./operator-history-summary.json \
  ./operator-history.tar.gz

The optional summary is sanitized, but the verification key is a secret. Do not put the key on a command line, in a ticket, or in source control.

Destructive and guarded CLI actions¶

Several commands are safe in their default mode but expose a separately guarded mutation. Review the target and keep a verified backup before using them.

# Remove generated deployment-check state and evidence files.
sudo ASESTACK_DEPLOYMENT_CHECK_CLEANUP_CONFIRM=delete \
  ase deployment-cleanup cleanup

# Apply the planned R2 lifecycle rule.
sudo ASESTACK_EVIDENCE_R2_LIFECYCLE_CONFIRM=apply \
  ase evidence-sync lifecycle-apply

Deployment cleanup creates a control-plane backup by default. Do not set ASESTACK_DEPLOYMENT_CHECK_CLEANUP_BACKUP=false unless a verified backup already exists.

ase release-check does not run the guarded deployment check or upload evidence unless the corresponding opt-in variables are set. Keep those opt-ins out of routine health checks. Application-level operations such as Docker, Nginx, firewall, file writes, database transfers, backup transfers, and restores have their own controller and managed-host guards; see Guarded actions.

Configuration used by the CLI¶

The helper defaults to these installed paths:

Purpose	Path
Application	`/opt/asestack`
Runtime environment	`/etc/asestack/asestack.env`
Controller data	`/var/lib/asestack`
Nginx visitor log	`/var/log/nginx/asestack-control-access.log`

Most overrides are intended for custom packaging or test environments. For the supported runtime settings, see the configuration reference.