CLI reference

Four binaries take a command line. In normal use you only ever run the first, with the command the dashboard gives you; the rest exist for manual setups, scripted rollout and recovery.

Run any of them with no arguments, or with --help, for its own usage text. On Windows, running aethercert-installer with no arguments opens the graphical setup window instead.

aethercert-installer

aethercert-installer install --api <url> --token <token> [options]
aethercert-installer repair [options]
aethercert-installer uninstall [--all | --agent --connector --update-service] [--purge]
aethercert-installer status
aethercert-installer gui
aethercert-installer version

install enrolls with a one-time token, downloads whichever component the token was minted for - that is decided in the dashboard, not on the command line - and registers and starts it as an operating-system service, alongside the shared tray icon and the Update Service. Run it as Administrator on Windows or with sudo on Linux. It prints the resolved config path and binary path on stdout when it finishes.

Common

Windows service

With --service-account, the installer grants that account Log on as a service, verifies the credentials work as a service logon before creating the service, and waits for the service to report running afterwards. A wrong password, a disabled account or a Deny log on as a service policy is reported as exactly that rather than as a generic start failure. The password never reaches a log line or an error message.

Fleet agent

CA connector

Companions

repair re-registers the services, refreshes the Apps & Features entries and reinstalls the tray icon and Update Service, using the credentials already on the host - no token needed. Takes --component agent|ca_connector, --redownload to also replace the binaries with the current build, and the --no-*, --lang and --quiet flags above.

uninstall stops and removes the selected components. --purge also deletes the binaries, configuration and logs; without it a later install reuses this host's existing enrollment. Name what to remove: --all, or any of --agent, --connector, --update-service.

status prints what is installed on this host - component, version, service state, binary and config paths and whether each exists, and the control plane it points at - and exits 0 either way, which makes it safe as a configuration-management check.

aethercert-agent

aethercert-agent enroll --api <url> --token <token> [--config <path>]
aethercert-agent run [--config <path>]
aethercert-agent uninstall
aethercert-agent version

For manual setups only - a container, or your own process supervisor. enroll writes configuration without registering a service; run runs in the foreground, or under the Windows SCM or systemd if a service was registered. It exits cleanly on SIGTERM and Ctrl+C.

uninstall stops and removes the service, leaving the binary and configuration in place. On Windows it also removes the Apps & Features entry - this is exactly what clicking Uninstall there runs.

aethercert-ca-connector

aethercert-ca-connector enroll --api <url> --token <token> --public-url <url> --ca-config <name> [options]
aethercert-ca-connector run [--config <path>]
aethercert-ca-connector preflight [--config <path>]
aethercert-ca-connector uninstall
aethercert-ca-connector version

Windows only. Run enroll as Administrator, on the CA server itself, using an account with Issue and Manage Certificates on the CA and Enroll on the template.

enroll pairs without installing a service, and has no --service-account option of its own - that flag lives on aethercert-installer install. Afterwards, register the service with aethercert-installer repair --component ca_connector (which does take --service-account / --service-password) or by hand with sc.exe create ... obj= ..., and separately run aethercert-update-service install for automatic updates.

preflight runs a read-only readiness check - service account, Windows service, CA reachability, template issuable status and permissions - and prints OK or the exact step still needed for each. It changes nothing and exits non-zero only when the connector cannot issue as configured. See The CA connector.

aethercert-update-service

aethercert-update-service install
aethercert-update-service run
aethercert-update-service update --agent | --connector
aethercert-update-service uninstall
aethercert-update-service version

install copies the binary to the standard location and registers a service, always as LocalSystem on Windows. Order does not matter - installed before the agent, it simply has nothing to update yet. It reads the same on-disk config.json the agent or connector already wrote, so no separate enrollment is needed.

update --agent or --connector downloads and applies whatever build the control plane currently has for that component, skipping the auto-update gate but not the verification. This is the manual path for a host pinned to its current version; the agent's settings page shows this exact command when automatic updates are off. It does not require the service itself to be installed or running.

The tray

aethercert-tray takes no command line. It is Windows-only, embedded in the installer, and launched for the logged-in user. Its menu offers Check for updates, Open logs, Sync now and Quit - each scoped to whichever backends are present on the host, and as a submenu when both the agent and the connector are. Quit exits the tray only; the services keep running.

Exit codes

Every command exits 0 on success and 1 on failure, with two deliberate exceptions:

• aethercert-installer status always exits 0, so "nothing installed" is not indistinguishable from a real failure.
• aethercert-ca-connector preflight exits non-zero only when the connector genuinely cannot issue - a check it could not confirm either way is a warning, not a failure.

An install that finishes with warnings - an optional companion that could not be installed

• still exits 0 and says how many warnings there were and where the log is.