> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install CostHQ CLI and Node.js Package

> Install CostHQ globally with npm. Includes build tool requirements for SQLite, binary list, and platform-specific setup for macOS, Linux, and Windows.

CostHQ requires **Node.js 16 or later** and installs as a global npm package. The embedded SQLite driver ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) uses native code, so your system needs C/C++ build tools available during installation. On most platforms, prebuilt binaries are provided and compilation is skipped automatically.

<Warning>
  If `npm install -g costhq` fails with a native compilation error, install the build tools for your platform (see the Prerequisites table below) and then re-run the install command. Skipping this step is the most common cause of installation failures.
</Warning>

<Steps>
  <Step title="Install build tools for your platform">
    CostHQ's SQLite driver compiles a small native module during installation. Install the correct build tools for your operating system before proceeding.

    | Platform            | Command                                           |
    | ------------------- | ------------------------------------------------- |
    | **Ubuntu / Debian** | `sudo apt-get install -y build-essential python3` |
    | **macOS**           | `xcode-select --install`                          |
    | **Windows**         | `npm install -g windows-build-tools`              |
    | **Alpine**          | `apk add build-base python3`                      |

    If prebuilt binaries are available for your platform and Node.js version, npm downloads them directly and skips compilation entirely.
  </Step>

  <Step title="Install CostHQ globally">
    Run the global install command. This installs the `costhq` and `cs` binaries on your PATH.

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g costhq
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify the installation">
    Confirm that the `cs` binary is available and shows the expected version.

    ```bash theme={null}
    cs --version
    ```

    You should see output like `3.1.1`. If the command is not found, ensure your global npm bin directory is on your `PATH`.
  </Step>
</Steps>

## Binaries Installed

Installing `costhq` places two binaries on your system:

| Binary   | Purpose                                      |
| -------- | -------------------------------------------- |
| `costhq` | Main CLI — all session and tracking commands |
| `cs`     | Alias for `costhq`                           |

Use `cs` for day-to-day work.

## Custom Database Path

By default, CostHQ stores all session data in `~/.costhq/sessions.db`. Set the `COSTHQ_DATA_DIR` environment variable to use a different location — useful for test isolation or keeping separate databases per project.

```bash theme={null}
# macOS / Linux
export COSTHQ_DATA_DIR=~/projects/client-a/.costhq.db

# Windows PowerShell
$env:COSTHQ_DATA_DIR = "C:\projects\client-a\.costhq.db"
```

The database file and its parent directory are created automatically on first use.

## Data Location Reference

| Platform      | Default path                              |
| ------------- | ----------------------------------------- |
| macOS / Linux | `~/.costhq/sessions.db`                   |
| Windows       | `C:\Users\<username>\.costhq\sessions.db` |

You're all set. Continue to [Quick Start](/quickstart) to track your first session.