CLI Installation

Install the Hookbase CLI on your system.

npm (Recommended)

The easiest way to install the CLI is via npm:

npm install -g @hookbase/cli

Verify installation:

hookbase --version

npx (No Installation)

Run commands without installing:

npx @hookbase/cli login
npx @hookbase/cli tunnels start 3000

From Source

Clone and build from source:

git clone https://github.com/HookbaseApp/cli.git
cd cli
npm install
npm run build
npm link

Authentication

After installation, authenticate with your account:

hookbase login

This opens a browser for OAuth authentication. Credentials are stored securely in your system config.

API Key

For CI/CD or automated environments, use an API key:

# Set via environment variable (recommended for CI)
export HOOKBASE_API_KEY="whr_live_abc123..."
hookbase sources list
 
# Or use interactive login with API key
hookbase login --api-key "whr_live_abc123..."

Verify Authentication

hookbase whoami

Output:

Hookbase CLI Status
 
User:         [email protected]
Display Name: John Doe
Organization: my-company

Configuration

Configuration File

The CLI stores configuration in your home directory:

macOS/Linux: ~/.config/hookbase/config.json
Windows: %APPDATA%\hookbase\config.json

View Configuration

# Show all config
hookbase config
 
# Show config file path
hookbase config --path
 
# Output as JSON
hookbase config --json

Environment Variables

Configure the CLI using environment variables:

Variable	Description
`HOOKBASE_API_KEY`	API key for authentication
`HOOKBASE_API_URL`	Custom API URL (default: https://api.hookbase.app)
`HOOKBASE_ORG_ID`	Default organization ID
`HOOKBASE_DEBUG`	Enable debug logging (`true` or `1`)

Example .env file for a project:

HOOKBASE_API_KEY=whr_live_abc123...
HOOKBASE_ORG_ID=org_xyz789

Multiple Organizations

If you have access to multiple organizations:

# View current organization
hookbase whoami
 
# The CLI uses the organization from your login session
# To switch, log out and log in to a different organization
hookbase logout
hookbase login

Updating

npm

npm update -g @hookbase/cli

From Source

cd cli
git pull
npm install
npm run build

Uninstalling

npm

npm uninstall -g @hookbase/cli

Clean Up Config

# macOS/Linux
rm -rf ~/.config/hookbase
 
# Windows
rmdir /s %APPDATA%\hookbase

Troubleshooting

Command Not Found

Ensure npm global bin directory is in your PATH:

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

Permission Denied (Linux/macOS)

If you get permission errors with global npm install:

# Option 1: Use a Node version manager (recommended)
# Install nvm: https://github.com/nvm-sh/nvm
nvm install node
npm install -g @hookbase/cli
 
# Option 2: Change npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$PATH:$HOME/.npm-global/bin"
npm install -g @hookbase/cli

Authentication Failed

Check if your API key is valid and not expired
Verify the key has required permissions
Ensure you're using the correct organization

# Test authentication
hookbase whoami
 
# Re-authenticate if needed
hookbase logout
hookbase login

Network Issues

If behind a corporate proxy:

# Set proxy for npm
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
 
# Set proxy for the CLI
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
hookbase login

Debug Mode

Enable verbose logging for troubleshooting:

export HOOKBASE_DEBUG=true
hookbase sources list

Getting Help

# General help
hookbase --help
 
# Command-specific help
hookbase tunnels --help
hookbase sources create --help
 
# Launch interactive dashboard
hookbase dashboard

Next Steps

Commands Reference - Full command documentation
Tunnels Guide - Using tunnels for local development
API Reference - REST API documentation