Getting Started

HedHog helps you scaffold headless APIs, compose reusable libraries, and ship a modular admin panel with RBAC permissions.

This guide focuses on installing the HedHog CLI, the recommended entry point for creating and managing HedHog projects.

Before installing the CLI, make sure your environment has:

• Node.js 18+
• npm 9+, or another npm version compatible with global package installation
• pnpm, required by several CLI workflows
• Git, required to clone templates and manage project version control
• Docker and Docker Compose, required by the default database flow in hedhog new

Install HedHog CLI globally with npm:

npm i -g @hed-hog/cli

After installing, confirm that the command is available:

hedhog --version
hedhog --help

If hedhog responds in your terminal, the global installation is ready.

With the CLI installed, you can create a new project right away:

hedhog new my-project

Then enter the project directory:

cd my-project

After the scaffold is ready, the usual local run flow is:

# Install dependencies if you created the project with --skip-install
pnpm install

# Start the local development environment
pnpm dev

If your generated project uses the default local database stack, make sure Docker Desktop or your local Postgres service is available before starting the app.

If the template exposes app-specific scripts, you can also inspect package.json and use the targeted commands provided there.

• The first run may take a bit longer while dependencies, generated files, or database containers finish initializing.
• Once the dev server is ready, open the local URL shown in the terminal.
• If the project includes an admin app, also open its local route to confirm the full stack is running correctly.

If you need to overwrite an existing directory, use:

hedhog new my-project --force

To update to the latest published version, run:

npm i -g @hed-hog/cli@latest

To remove the global installation:

npm uninstall -g @hed-hog/cli

Right after installing Node.js with winget on Windows, running npm --version in PowerShell may fail with:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

This happens because PowerShell's default Execution Policy blocks running .ps1 scripts, including npm's. Fix it by allowing locally created/signed scripts for your user:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

• Close and reopen the terminal after installing Node.js with winget, so the updated PATH is picked up.
• Run node --version and npm --version again to confirm both are recognized.

• Close and reopen your terminal.
• Confirm that the npm global binary directory is in your PATH.
• Run npm prefix -g to check the current global npm prefix.

• On Windows, run the terminal with the required permission level.
• Avoid mixing global packages between different Node.js installations.

• Install pnpm and validate it with pnpm --version.
• The hedhog new command checks for pnpm before starting the scaffold process.

When hedhog new detects that git and/or pnpm are missing, it asks interactively: "Would you like to install them automatically now?" Answering "Yes" installs pnpm automatically via npm without issues.

For git, the package manager the CLI reaches for depends on what is already present on the machine. On modern Windows 11 systems, winget is often pre-installed (bundled with App Installer) even when Chocolatey isn't. In that case, the CLI skips straight to winget install Git.Git instead of offering to install Chocolatey first. In other words, the detected package manager — and therefore the exact install path taken — can vary depending on what's already available on the target machine.

Known limitation: if winget's msstore source has a certificate problem, its multi-source search becomes ambiguous and the automatic git install fails, even though the winget source (non-msstore) works fine and already lists the Git package correctly:

0x8a15005e: The server certificate did not match any of the expected values.

When this happens, the CLI correctly falls back to the "Required tools missing" box and directs you to install git manually. Workarounds: reset the winget source (winget source reset --force) or install git manually before running hedhog new again.

In non-interactive runs (no TTY — for example scripts, CI, or vagrant winrm -c "..."), the CLI never prompts: it goes straight to the "Required tools missing" box and exits with Required tools still missing: git (or the name of whichever tool is absent).

When hedhog new detects a failed Postgres connection, it tries to spin up a database container automatically via Docker Compose. On Windows, if the Docker CLI is installed (for example via winget install Docker.DockerDesktop) but the Docker Desktop engine was never started, the command fails even though docker --version works fine, because that command only talks to the Docker client, not the daemon:

unable to get image 'postgres:18': failed to connect to the docker API at
npipe:////./pipe/docker_engine; check if the path is correct and if the
daemon is running: open //./pipe/docker_engine: The system cannot find the
file specified.

Running docker info confirms this: the Client: section reports normally, while the Server: section fails with the same named-pipe error. You may also see Error response from daemon: Docker Desktop is unable to start.

• Update the WSL2 kernel: wsl --update.
• Open Docker Desktop manually and wait for the whale tray icon to show "Running" (green). It may prompt you to enable WSL2/Hyper-V or to restart Windows.
• If you still see "Docker Desktop is unable to start", start the engine manually from Docker Desktop's UI (Settings > General).
• Before retrying, validate with docker info: it should return details under Server: with no pipe error.
• Run hedhog new <project> again.

If hedhog new failed partway through, the project folder was already created, so retrying with the same name fails with:

A folder with the name "X" already exists. Process stopped.

Remove the folder first, then retry:

npx rimraf <project>
hedhog new <project>