Should output v18.0.0 or higher

This guide will walk you through installing and setting up the HooksDash CLI.

Prerequisites

Before installing the CLI, ensure you have:

Node.js 18 or higher
npm 9 or higher (or pnpm/yarn)
A HooksDash account (sign up at hooksdash.ibadsiddiqui.dev)

Check Node.js Version


node --version
# Should output v18.0.0 or higher

Check npm Version


npm --version
# Should output 9.0.0 or higher

Installation Methods

Method 1: Global Installation (Recommended)

Install the CLI globally to use it from anywhere:


npm install -g hooksdash

Verify installation:


hooksdash --version
# Should output: 1.0.0

Method 2: npx (No Installation Required)

Run the CLI without installing:


npx hooksdash login
npx hooksdash forward --port 3000

Note: This downloads and runs the CLI each time, which is slower than global installation.

Method 3: Local Project Installation

Install as a dev dependency in your project:


npm install --save-dev hooksdash

Add scripts to your package.json:


{
  "scripts": {
    "tunnel": "hooksdash forward --port 3000"
  }
}

Run via npm scripts:


npm run tunnel

Authentication

After installation, you need to authenticate with your HooksDash account.

Option 1: Browser Authentication (Recommended)


hooksdash login

This will:

Open your browser to the HooksDash authentication page
Prompt you to log in (if not already logged in)
Display a success message in the CLI
Store your API key securely

Example output:

✔ Authentication session created
Opening browser for authentication...
If browser doesn't open, visit: https://hooksdash.ibadsiddiqui.dev/cli-auth?session=...
⠹ Waiting for authentication in browser...
✔ Authentication completed!
✔ Successfully authenticated!
Welcome! You're logged in as user@example.com
Tier: FREE

Option 2: Manual API Key

If you prefer not to use browser authentication:

Log in to hooksdash.ibadsiddiqui.dev
Go to Settings → API Keys
Copy your API key
Use it to log in:


hooksdash login --api-key hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Verify Installation

Check that you're logged in:


hooksdash status

Expected output:

✔ Logged in
API Key: hd_abc****xyz

Configuration

The CLI stores configuration in:

macOS/Linux: ~/.config/hooksdash/config.json
Windows: C:\Users\<username>\.config\hooksdash\config.json

This file contains your API key and settings. Do not commit this file to version control.

Configuration File Structure


{
  "apiKey": "hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "apiUrl": "https://hooksdash-api.ibadsiddiqui.dev/api"
}

Updating the CLI

Global Installation


npm update -g hooksdash

Local Installation


npm update hooksdash

Check the new version:


hooksdash --version

Uninstalling

Global Installation


npm uninstall -g hooksdash

Local Installation


npm uninstall hooksdash

Remove Configuration


# macOS/Linux
rm -rf ~/.config/hooksdash

# Windows
rmdir /s "%USERPROFILE%\.config\hooksdash"

Troubleshooting

Command Not Found

If you get command not found: hooksdash after global installation:

Check npm global bin path:


npm bin -g

Add it to your PATH (macOS/Linux):


# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm bin -g)"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

Windows:

Run as Administrator: npm config get prefix
Add that path to your System Environment Variables

Permission Errors (macOS/Linux)

If you get EACCES permission errors:

Option 1: Use a version manager (Recommended)

Use nvm or volta to manage Node.js:


# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js via nvm
nvm install 18
nvm use 18

# Now install CLI
npm install -g hooksdash

Option 2: Change npm global directory


mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

# Now install CLI
npm install -g hooksdash

Authentication Issues

Browser doesn't open:

Copy the authentication URL from the terminal and open it manually in your browser.

Session expired:

The authentication session expires after 5 minutes. Run hooksdash login again.

Invalid API key:

If you're using manual API key authentication and get an error:

Verify the API key in your HooksDash dashboard
Make sure you copied the entire key (starts with hd_)
Try regenerating your API key in the dashboard

Connection Issues

Cannot connect to API:

Check your internet connection and try:


# Test connection
curl https://hooksdash-api.ibadsiddiqui.dev/api/health

# If you're behind a proxy, set proxy environment variables
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

Custom API URL (for development):


hooksdash login --api-url http://localhost:4000/api

Firewall Issues

The CLI uses WebSocket connections on standard ports (80/443). If your firewall blocks WebSockets:

Check your firewall settings
Allow WebSocket connections to *.hooksdash.ibadsiddiqui.dev
Contact your network administrator if needed

Platform-Specific Notes

macOS

Uses Keychain for secure API key storage (future enhancement)
Works with both Intel and Apple Silicon

Linux

Configuration stored in ~/.config/hooksdash/
Requires Node.js 18+ (check with node --version)

Windows

Configuration stored in %USERPROFILE%\.config\hooksdash\
Use PowerShell or Command Prompt
Git Bash is also supported

Docker

To use the CLI in Docker:


FROM node:18-alpine

# Install CLI globally
RUN npm install -g hooksdash

# Set working directory
WORKDIR /app

# Copy your app
COPY . .

# Install dependencies
RUN npm install

# Start with tunnel
CMD ["sh", "-c", "hooksdash forward --port 3000 & npm start"]

Note: You'll need to handle authentication in your container setup.

Getting Help

If you encounter issues:

Check Common Issues above
Search GitHub Issues
Create a new issue with:
- CLI version (hooksdash --version)
- Node.js version (node --version)
- Operating system
- Error message
- Steps to reproduce

CLI Installation