CLI Documentation

Add analytics to your frontend projects with one command

Installation Commands Examples Troubleshooting

Installation

NPM

npm install -g @happenstance/cli

Yarn

yarn global add @happenstance/cli

pnpm

pnpm add -g @happenstance/cli

Verify Installation

Check that the CLI was installed correctly:

happenstance --version

Quick Start

Get started with Happenstance in 3 steps:

1

Authenticate

happenstance login
2

Navigate to your project

cd your-project
3

Initialize analytics

happenstance init

This will auto-detect your framework and set up tracking.

Commands

happenstance init

Initialize Happenstance analytics in your project. Detects your framework, generates tracking events, and creates a pull request with the integration code.

Options

--repo

Specify GitHub repository (format: owner/repo)

Default: Auto-detected from git remote

--platform

Deployment platform (netlify, vercel, railway, render, cloudflare)

Default: Auto-detected from config files

--no-webhook

Skip GitHub webhook setup

--no-rebuild

Skip triggering automatic rebuild

Example

happenstance init --repo acme/my-app --platform vercel

happenstance login

Authenticate with Happenstance using OAuth. Opens a browser window to complete authentication.

What it does

  • → Opens browser for GitHub OAuth
  • → Stores auth token locally (~/.happenstance)
  • → Verifies connection to Happenstance API

Example

happenstance login

happenstance status

Check the setup status of Happenstance in the current project. Shows tracked events, API key status, and configuration.

Output includes

  • ✓ Repository connection status
  • ✓ Detected framework
  • ✓ Number of tracked events
  • ✓ API key presence (not the key itself)
  • ✓ Last sync timestamp

Example

happenstance status

Common Workflows

First-time Setup

# Install CLI globally
npm install -g @happenstance/cli

# Authenticate
happenstance login

# Navigate to your project
cd my-react-app

# Initialize analytics
happenstance init

The CLI will create a pull request with all tracking code integrated.

CI/CD Integration

# GitHub Actions example
- name: Setup Happenstance
  run: |
    npm install -g @happenstance/cli
    happenstance status

# Check if analytics are properly configured
- name: Verify Analytics
  run: happenstance status --json | jq '.events_count'

Managing Multiple Projects

# Project A (React)
cd project-a
happenstance init --repo myorg/project-a

# Project B (Vue)
cd ../project-b
happenstance init --repo myorg/project-b

# Check status of all projects
for dir in project-*; do
  cd $dir
  echo "Status for $dir:"
  happenstance status
  cd ..
done

Troubleshooting

Authentication Issues

If login fails or token expires:

# Remove stored credentials
rm -rf ~/.happenstance

# Re-authenticate
happenstance login

Git Not Detected

Manually specify repository:

happenstance init --repo owner/repo-name

Framework Not Detected

The CLI auto-detects: React, Vue, Svelte, Angular, Next.js, SvelteKit

If detection fails, check:

  • → package.json exists in project root
  • → Framework dependencies are listed
  • → You're in the correct directory

Need More Help?

View detailed help for any command:

happenstance --help
happenstance init --help

Report issues: GitHub Issues