# Install and maintain HypAware Canonical: https://hypaware.ai/docs/cli Install HypAware, check its background service, and keep the installation up to date. For the syntax and behavior of every command, see the [HypAware CLI command reference](https://hypaware.ai/docs/cli-reference/index.md). ## Requirements - Node.js 22.12 or later. - macOS with `launchd`, Linux with a `systemd` user service, or Windows with Task Scheduler, for the persistent background service. A container or CI host without one can run `hyp daemon run` in the foreground instead; see [CI and headless deployment](https://hypaware.ai/docs/integrations/ci-and-headless/index.md). - An interactive terminal for the guided setup. ## Install HypAware Install the CLI globally, then run the guided setup: ```sh npm i -g hypaware hyp setup ``` Select **Sync to the cloud** to store your recordings on HypAware Cloud or choose **Local only** to keep recordings on your host. To change this later, see [connect a host](https://hypaware.ai/docs/team-setup/index.md#connect-a-host). Setup then asks which AI clients to record, installs the background service, connects the clients you selected, and imports their supported session history. If a valid configuration already exists, `hyp setup` lets you reconfigure the setup. `hyp setup` runs the same way on Windows as on macOS and Linux. On any of them you can instead install the service with `hyp daemon install` and connect each client with `hyp client attach `. For an unattended local installation, specify each choice: ```sh hyp setup --yes \ --source claude \ --source otel \ --client claude \ --export keep-local \ --retention-days 90 ``` `--dry-run` previews an unattended setup: it reports what would be written and writes no configuration. The flag always runs setup non-interactively, so name the choices to preview with `--yes`, `--source`, `--client`, or `--from-file`; on its own it stops with "no sources selected". The guided setup has no preview. If a configuration already exists, add `--force` to replace it. HypAware backs up the existing configuration before replacement. ## Check the installation ```sh hyp status ``` ```output HypAware · Needs attention Daemon Running Storage 37 MB · 90-day retention Sharing Organization sync configured new folders: sync without asking (`hyp privacy folders ask` to be asked instead) Clients Status Data claude Telemetry may be interrupted Sync codex Recording Sync Sync = organization sharing policy, not delivery confirmation. Attention ! claude: transcripts active 1m ago; last telemetry 21m ago. Next: hyp daemon restart More details: hyp status --verbose ``` Status reports the background service, clients, storage, and anything that needs attention, with guidance to help resolve problems. For capture checks, see [clients and history](https://hypaware.ai/docs/clients/index.md); for failures, see [troubleshooting](https://hypaware.ai/docs/troubleshooting/index.md). ## Manage the background service The daemon keeps capture and scheduled sync running after you close the terminal. Setup installs it as a per-user service. On macOS, its LaunchAgent runs while you are logged in. On Linux, its systemd user service requires user-session support; see [headless deployment](https://hypaware.ai/docs/integrations/ci-and-headless/index.md#long-lived-headless-hosts) for hosts that must keep running after logout. On Windows, it is a per-user Scheduled Task, `\hypaware\`, where `` is your Windows security identifier. It runs as you and needs no administrator rights. It stops when you sign out and starts again when you next sign in. If the daemon crashes, Windows relaunches it within about a minute; a clean exit, such as the one `hyp daemon stop` asks for, leaves it stopped. No console window opens: the task runs the daemon through a generated launcher, `.hyp\hypaware\daemon-launcher.vbs` in your user profile (next to the `logs` directory), using `wscript`. Install writes the launcher, and `hyp daemon uninstall` deletes it along with the task. On Windows, `hyp daemon stop` first asks the daemon to exit cleanly. If it is still running after 10 seconds, stop force-ends the task and the daemon it launched, and says so. `hyp daemon restart` stops the daemon the same graceful way and then runs the task again; it force-ends the task only when the stop request does not land. ```sh hyp daemon status hyp daemon restart ``` Use the [daemon reference](https://hypaware.ai/docs/cli-reference/index.md#manage-the-daemon) for start, stop, install, and foreground operation. ## Reconfigure an installation For an ordinary interactive reconfiguration, run: ```sh hyp setup ``` Select **Reconfigure** in the menu. HypAware preserves a centrally managed configuration layer and changes only the choices this host owns. For unattended replacements and configuration files, see [repeatable configuration](https://hypaware.ai/docs/configuration/index.md#make-a-repeatable-setup). ## Update HypAware HypAware updates automatically by default when installed globally and running as a background service. To update now: ```sh hyp update ``` The command installs the latest release and restarts the background service. > **Caution:** `hyp update` and the automatic check both take the registry's latest release > with no major-version bound, so an update can cross a breaking boundary. > HypAware has no operator-controlled migration rollback, and the updater's > boot-failure recovery is not a backup of your data. Before a major version, > read its release notes and copy `~/.hyp` to a new backup path, then install the > reviewed version and validate before resuming ordinary use: ```sh npm install -g hypaware@NEXT_MAJOR_VERSION hyp version hyp config validate hyp daemon install hyp status ``` Replace `NEXT_MAJOR_VERSION` with the version you reviewed. Set top-level `"auto_update": false` and restart the daemon first, or the next automatic check moves off the version you pinned; centrally managed policy may own that choice. Do not assume `--yes` accepts a breaking migration, because no such acceptance contract exists. If validation fails, stop and restore the saved copy. ## Reinstall or recover the current version If the CLI binary or service definition is missing but your state is intact, reinstall the package and service: ```sh npm install -g hypaware hyp daemon install hyp status ``` To restore a known-good configuration, follow [repeatable configuration](https://hypaware.ai/docs/configuration/index.md#make-a-repeatable-setup). Use `hyp attach ` for any configured client that status reports as detached, replacing `` with its name, such as `claude` or `codex`. ## Uninstall ```sh hyp leave # if this host is enrolled in Cloud hyp daemon uninstall npm uninstall -g hypaware ``` Daemon uninstall restores managed client settings and retains local configuration and recordings. To delete recorded data, see [privacy](https://hypaware.ai/docs/privacy/index.md#deleting-what-was-already-recorded). Copies already synced to Cloud or exported to files are not removed by uninstall.