# Install the CLI > Install the hansard command with npm, run setup, and confirm that your archive and watcher are working. The CLI provides the `hansard` command and the browser version of the app. Use it in terminals and scripts, and to connect Hansard to your coding agents. To have a coding agent install and set up Hansard for you, see [Set up with an agent](https://www.hansard.dev/getting-started/agent-setup/). For the desktop app, which includes Node.js, see [Install the app](https://www.hansard.dev/getting-started/download/). ## Requirements - Node.js 22.12 or newer (or 20.19 or newer on Node.js 20), with npm. Node.js 21 is not supported. Check your version with `node --version`. - macOS, Linux, or Windows. - Free disk space for your history. Setup measures it before importing. On macOS and Linux, run the commands in a terminal. Linux uses the browser app through `hansard web`. Login startup uses a systemd user service on Linux and a LaunchAgent on macOS. If your Linux system has no systemd user session, keep `hansard watcher start --foreground` running in a terminal or your service manager. On Windows, run the commands in PowerShell or Command Prompt. Hansard reads provider stores from their Windows locations, including `%APPDATA%`, and honors provider home overrides such as `CODEX_HOME` and `CLAUDE_CONFIG_DIR`. SQLite and ZIP readers are bundled; separate `sqlite3` and `unzip` programs are not required for imports. The default Hansard home is `.hansard` under `HOME`, or `USERPROFILE` when `HOME` is unset. With neither variable set, Hansard uses the operating system home. Set `HANSARD_HOME` to the absolute path of another local directory, or a path under `~/`, to use it instead. Login startup uses a current-user Scheduled Task with no administrator privileges. Windows x64 desktop builds include Node.js and use a per-user installer. See the [download page](https://www.hansard.dev/getting-started/download/) for available installers and their signing status. To install one you downloaded, run `hansard app install --from .\Hansard-windows-x64.exe`. ## Tested platforms **Verified** identifies the completed checks named in the table. **Preview** means the implementation is available, with release acceptance still incomplete. **Planned release** means a build target exists but no installer is published. | Platform | CLI | Desktop app | Browser extension | | ------------------- | ---------------------------------- | --------------------------------- | ----------------- | | macOS Apple silicon | Preview | Verified signing and notarization | Preview | | macOS Intel | Preview | Planned release | Preview | | Windows x64 | Preview with recorded native tests | Preview, unsigned installer | Preview | | Linux | Preview | No native installer | Preview | The automated test configuration covers Linux with Node.js 20, 22, and 24, plus macOS and Windows with Node.js 24. Package installation trials also cover all three operating systems. These configured checks do not establish a passing run for every release or a separate Intel CLI result. Recorded native Windows trials cover an earlier release, so the current CLI remains labeled preview. The Apple silicon download has verified signing and notarization. Independent clean-machine installation and signed updates between two versions remain pending. The Windows download is an unsigned preview. Intel has a desktop build target but no published download. Check [Install the app](https://www.hansard.dev/getting-started/download/) for current artifacts. On Linux, use the CLI and browser app. The extension targets Chromium browsers with Manifest V3 and Chrome 109 or newer. Its preview status applies to each operating system above. Provider capture checks do not establish complete browser and operating-system coverage. See [Browser capture](https://www.hansard.dev/imports/browser-capture/) for source-specific limits. Firefox and Safari extension packages are not available. ## Install the package ```sh npm install -g hansard hansard --version ``` Install the package globally. Your agents run the `hansard` command when they recall past conversations, so it must be on your `PATH`. If your shell cannot find `hansard` after installing, add npm's global bin directory to your `PATH` instead of installing a second copy. Installing the package does not set anything up. Run `hansard init` next. Avoid running setup through `npx`, `pnpm dlx`, or `bunx`. Those commands can run a cached copy that later disappears, leaving agent integrations or login startup pointing at it. `hansard init --dry-run` names the agent files setup would change and warns when their launcher comes from a temporary package cache. ## Run setup To preview setup without writing anything, run: ```sh hansard init --dry-run ``` The preview lists the history Hansard found and its size, estimates the disk space the archive needs, and shows every change setup could make, including each agent file it would change. When you are ready, run the setup wizard: ```sh hansard init ``` To choose the initial history window, use `hansard init --since 30d` for the past 30 days or `hansard init --since all` for all available history. The option also accepts hours, minutes, and ISO dates. This selects the initial import window. The setup wizard reviews ongoing archiving separately. In checklists, use the arrow keys to move, Space to select, and Enter to confirm. The wizard asks, in order: 1. Where to keep the archive, `~/.hansard/data` by default, and names for this device and for you. Hansard records these names on archived conversations and uses the device name for sync. 2. Whether to redact common secrets in the searchable copy. Redaction is on by default. The original copies are kept unredacted. 3. Which sources to import now and which to watch for new conversations. Hansard scans your harness folders first and shows how much history each one has. 4. Whether agents in the same project can message each other and start helper agents. Both questions start unanswered. Helpers require messaging. Skipping or `--yes` alone keeps both off. A message can announce that an API is ready for tests. A helper can review a change. 5. How Hansard runs: background archiving, plan usage, local meaning search, labeling, update checks, and link icons. **Claude Code activity** is on by default. It reports timing and errors to Hansard on this Mac. Accepted setup adds a few lines to Claude Code's settings. Turning it off writes nothing to those settings. Existing exports elsewhere remain unchanged. 6. Which extras to turn on: recall in your agents, copying referenced screenshots and PDFs into the archive, and the interactive mode that opens when you run `hansard` with no command (on by default). 7. Whether to import your existing history now and connect Slack notifications. 8. Whether to sync to Cloudflare R2, Amazon S3, or another S3-compatible store. Setup offers this only after the local archive is ready. To add sync later, run `hansard sync configure`. Before importing, setup compares the size of your history with the free space at the archive location. The estimate includes the original copies, the searchable archive, and a reserve of free space. If there is not enough space, or the space cannot be checked, the import does not start. A size shown as "at least" comes from a scan that stopped early in a very large folder. When setup finishes, it prints commands for opening Hansard and checking status. Imports continue in the background. ### Run setup again Running `hansard init` again offers to keep, edit, or reset your saved source choices, then shows one review before saving. To change preferences without importing again, run `hansard config setup`. If setup was interrupted, check where it stopped with `hansard init --status`, then run the same `hansard init` command again. Setup resumes from the step that did not finish. `hansard init --restart` discards an unfinished setup run. It does not delete configuration, integrations, or conversations already archived. ### Set up without prompts For scripts, pass your choices as flags. `--yes` alone leaves recall and login startup off, so name them explicitly: ```sh hansard init --yes --sources codex-cli,claude --watch-sources codex-cli,claude --since 30d --recall codex,claude --autostart --no-track-usage ``` On a new setup, `--autostart` also turns on plan usage tracking unless you add `--no-track-usage`. `--no-agent-collaboration` leaves agent messaging and helper agents off. Run `hansard help init` for every flag and `hansard help import` for source IDs. ## Check that setup worked ```sh hansard init --status hansard import status hansard status hansard doctor hansard watcher login status ``` | Command | What it shows | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | `hansard init --status` | Which setup steps finished. Imports can still be running after setup finishes. | | `hansard import status` | Progress of import runs. `hansard import follow` shows the current run live. | | `hansard status` | Watcher state, archive location, conversation counts per source, and recent imports. | | `hansard doctor` | Missing tools, source coverage, search index, login startup, and sync, with a command for each warning. | | `hansard watcher login status` | Whether the watcher starts at login. | A working setup has an archive, finished imports for the sources you chose, recall in the agents you chose, and a running watcher. If Hansard found no history, an empty archive is expected. Restart any agent that was already open so it loads recall. `hansard doctor --deep` runs slower checks across the whole archive, including importer versions and conversations whose original files are gone. To open the app in your browser, run: ```sh hansard web ``` The app opens at `http://127.0.0.1:7824`. On macOS and Windows, `hansard app` opens the desktop app instead. ## Optional tools Some sources and features use tools that may not be installed. `hansard doctor` reports which ones are missing. SQLite and ZIP readers are bundled on every platform. Imports do not require separate `sqlite3` or `unzip` programs. | Tool | Used for | | -------------- | ----------------------------------------------------------------------------------------- | | `rg` (ripgrep) | Faster `hansard history` search | | `zstd` | Compressed Codex session files, when your Node.js build has no built-in Zstandard support | ## Update the CLI ```sh npm install -g hansard@latest hansard watcher restart ``` The CLI checks npm for a newer version once a day and prints a notice when one is available. To turn the check off, run `hansard config set updates.checkOnStartup false` or set `HANSARD_NO_UPDATE_CHECK=1`. While the watcher runs, it refreshes the recall files in your agents after each update. Update every copy of Hansard on the computer, the desktop app and an npm installation alike. After an update, the watcher brings archived conversations up to the new release's files in the background. To turn this off, run `hansard config set archive.autoRefresh false`, then run `hansard rebuild --since all` once. An installation that does not run the watcher runs that command too. See [Refresh after updates](https://www.hansard.dev/reference/background-work/#refresh-after-updates). Some releases change how history is imported. Their [release notes](https://www.hansard.dev/releases/) name the command to run, such as `hansard rebuild` or `hansard update`. See [Refresh the archive](https://www.hansard.dev/getting-started/how-it-works/#refresh-the-archive). ## Uninstall ```sh hansard uninstall npm uninstall -g hansard ``` `hansard uninstall` stops the watcher, turns off login startup, and asks whether to delete `~/.hansard`. That folder holds your settings, the archive in its default location, and any saved account profiles. To keep them, add `--keep-data`. The command does not remove the recall commands and skills in your agents. It lists their paths so you can delete them. Uninstalling never changes your harnesses' own history. To start over with a fresh setup instead, preview a reset with `hansard reset --dry-run`.