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) 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.

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.

1. 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.

2. Install CostHQ globally

   Run the global install command. This installs the costhq and cs binaries on your PATH.

   npm

   npm install -g costhq
   
3. Verify the installation

   Confirm that the cs binary is available and shows the expected version.

   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.

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.

# 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 to track your first session.