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 from https://cdn.asestack.dev/latest/;
verifies the exact checksum plus independent immutable-release asset digests, sizes, names, and canonical GitHub URLs;
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.

Optional direct GitHub update status¶

The Settings update panel reads the public CDN's latest/release-metadata.json by default and needs no GitHub credential. If an operator deliberately sets ASESTACK_UPDATE_CHECK_URL to the private GitHub Releases API, use a separate fine-grained personal access token. Set resource owner asetho, limit repository access to aseStack, and grant repository Contents: Read-only permission. Choose an expiration that matches the maintenance policy; GitHub may require organization approval before the token can access the repository. The Releases API requires only that read permission. Do not copy a broad workstation gh credential to the controller.

Enter the token interactively into a dedicated root-owned file:

sudo install -d -o root -g root -m 0700 /etc/asestack-secrets
sudo bash -c 'umask 077; read -r -s -p "GitHub read token: " token; printf "\n"; printf "%s\n" "$token" > /etc/asestack-secrets/github-read.token'
sudo chown root:root /etc/asestack-secrets/github-read.token
sudo chmod 0600 /etc/asestack-secrets/github-read.token

Add only its path to /etc/asestack/asestack.env:

ASESTACK_GITHUB_TOKEN_FILE=/etc/asestack-secrets/github-read.token

Then reapply and restart the service wiring:

sudo ase repair
sudo ase health

The installer validates the source file and delivers a systemd credential copy to the unprivileged controller. Update checks attach the token only to exact HTTPS github.com or api.github.com requests, remove it for any other host, and never return it in Settings responses or job history. For the privileged install/update path, keep a current root-owned mode-0600 immutable-release JSON file and set ASESTACK_GITHUB_RELEASE_API_URL=file:///absolute/path/to/release.json. Installer, archive, checksum, and agent-updater downloads default to the public CDN; no asset overrides or GitHub credential are needed on the managed host. ASESTACK_CDN_BASE_URL can select another mirror, while explicit artifact URLs retain precedence. A packaged updater remains version-bound: if its version is no longer in latest/, use a newly verified current updater or explicit historical URLs. See the install guide for the independent workstation verification and metadata handoff.

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:

sudo /opt/asestack/deploy/update-agent.sh
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

When the controller uses a security entrance, store the full URL in a root-owned mode-0600 file and use --url-file /root/asestack-passkey-url. The checker uses an isolated cookie jar, keeps the URL out of process arguments, and omits the entrance path from its sanitized summary.

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

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.