CLI reference
Four binaries make up a host-side installation. In normal use you only ever run the first one, with the command the dashboard gives you; the rest exist for manual setups, scripted rollout and recovery.
| Binary | What it is |
|---|---|
aethercert-installer | Installs, repairs and removes everything else. The only one you normally invoke. |
aethercert-agent | The fleet agent - issues, deploys and renews certificates. |
aethercert-ca-connector | Windows only. Answers sign and revoke requests against a local CA. |
aethercert-update-service | Checks for and applies updates to the two above, once a day. |
Run any of them with no arguments 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.
Common flags
| Flag | What it does |
|---|---|
--api <url> | Control plane base URL. HTTPS only. |
--token <token> | The one-time token from the dashboard. |
--config <path> | Absolute path for the component's config.json. |
--lang en|de | Language for this command's own output. |
--quiet | Print warnings and failures only. |
Windows service
| Flag | What it does |
|---|---|
--service-account <user> | Run as this account instead of LocalSystem. Accepts CORP\user, .\user, user@corp, or a gMSA name ending in $. |
--service-password <pw> | Password for that account. Not needed for a gMSA. |
--manual-start | Register without auto-start. |
--no-start | Register without starting it now. |
Fleet agent
| Flag | What it does |
|---|---|
--check-in-interval <s> | Fallback idle check-in interval, 10-3600 seconds. Still bounded by your plan. |
CA connector
| Flag | Default | What it does |
|---|---|---|
--public-url <url> | Derived from the host's FQDN | Where fleet agents reach this host. |
--listen <addr> | :8443 | Local listen address. |
--ca-config <name> | Auto-detected if there is exactly one | The certreq/certutil -config target, <CAHostName>\<CAName>. |
--template <name> | WebServer | Certificate template to issue against. |
--tls-cert / --tls-key | The host's CA issues one | Your own listener certificate. |
--no-firewall-rule | Rule is added | Do not open the listen port inbound. |
Companions
| Flag | What it does |
|---|---|
--no-tray | Do not install the shared tray icon. |
--no-update-service | Do not install the update service. This host will then never update itself. |
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.
status prints what is installed on this host and exits 0 either way - useful 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.
Running the agent directly means updating it yourself
The agent never checks for or applies its own updates. Without the update service on
the host, aethercert-agent run stays on whatever build you put there.
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 uninstall
aethercert-ca-connector version
Windows only. Run enroll as Administrator, on the CA server itself, with an account
that has Issue and Manage Certificates on the CA and Enroll on the template.
| Flag | Required | Default |
|---|---|---|
--api <url> | Yes | |
--token <token> | Yes | One-time pairing token from Manage > Certificate Authorities > Connector |
--public-url <url> | Yes | Where this host is reachable from fleet agents on your internal network |
--ca-config <name> | Yes | <CAHostName>\<CAName> |
--template <name> | No | WebServer |
--listen <addr> | No | :8443 |
--tls-cert / --tls-key | No | The host's own CA issues one; failing that, a persisted self-signed certificate |
--config <path> | No | Platform default |
enroll pairs without installing a service. Afterwards, register and start the Windows
service yourself - with a dedicated service account - and separately run
aethercert-installer or aethercert-update-service install for automatic updates and
the tray icon. 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 Windows service,
always as LocalSystem. Order does not matter - installed before the agent, it simply has
nothing to update yet.
update --agent or --connector downloads and applies whatever build the control plane
currently has, skipping the auto-update gate. This is the manual path for a host pinned
to its current version; the agent's settings page shows this exact command when
auto-update is off. It does not require the service itself to be installed or running.
File locations
| Linux | Windows | |
|---|---|---|
| Agent binary | /opt/aethercert-agent/aethercert-agent | C:\Program Files\aethercert\agent\aethercert-agent.exe |
| Agent config | /etc/aethercert-agent/agent/config.json | %ProgramData%\aethercert\agent\config.json |
| Scripts directory | /etc/aethercert-agent/agent/scripts/ | C:\ProgramData\aethercert\agent\scripts\ |
| Service | systemd unit | AetherCertAgent in the Service Control Manager |
Agent configuration file
Most settings live in the dashboard. Two are local to the host, in config.json:
| Key | What it does |
|---|---|
certificate_scan_paths | Extra directories to include in the external certificate inventory, on top of the platform defaults. |
disable_certificate_scan | true turns the inventory off for this host entirely. |
Restart the agent service after editing it.