CLI

TownHall CLI

Command-line interface for managing forms and submissions directly from your terminal.

Installation

Install the CLI globally or use it directly with npx:

Global Installation

bash

npm install -g @townhall-gg/cli

Using npx (no install)

bash

npx @townhall-gg/cli --help

Requires Node.js 18+

The CLI requires Node.js version 18 or higher.

Authentication

Before using the CLI, you need to authenticate with your API key.

Create an API Key

Go to Settings → API Keys in your TownHall dashboard and create a new key with the following permissions:

forms:read - List and view forms
forms:create - Create new forms
submissions:read - View form submissions

bash

townhall login

# You'll be prompted for your API key:
# 🏛️  TownHall CLI Login
# 
# Get your API key from: https://townhall.gg/settings/api
# 
# ? Enter your API key: th_xxxxxxxxxxxx
# ✓ Authenticated!

Verify Authentication

bash

townhall whoami

# Output:
# 🏛️  TownHall Account
# 
# Email:     you@example.com
# Name:      Your Name
# User ID:   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 
# Available Workspaces:
#   ● My Workspace (my-workspace)

Commands Reference

Here's a quick reference of all available commands:

Command	Description
`townhall login`	Authenticate with your API key
`townhall logout`	Clear stored credentials
`townhall whoami`	Show current authenticated user
`townhall forms list`	List all forms in your workspace
`townhall forms get <formId>`	Get details about a specific form
`townhall forms create`	Create a new form interactively
`townhall submissions [formId]`	List recent submissions
`townhall init`	Initialize TownHall in your project

Managing Forms

List Forms

View all forms in your workspace:

bash

townhall forms list
# or
townhall forms ls

# Output:
# 📋 Forms (2)
# 
#   Contact Form
#   ID: abc123-xxxx-xxxx-xxxx-xxxxxxxxxxxx
#   Status: ● active  Submissions: 150
# 
#   Newsletter Signup
#   ID: def456-xxxx-xxxx-xxxx-xxxxxxxxxxxx
#   Status: ● active  Submissions: 89

Get Form Details

View details about a specific form:

bash

townhall forms get abc123-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Output:
# 📋 Contact Form
# 
# ID:          abc123-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# Status:      ● active
# Submissions: 150
# Created:     1/15/2024

Create a Form

Create a new form interactively:

bash

townhall forms create

# Output:
# 📝 Create New Form
# 
# ? Form name: Contact Form
# 
# ✓ Form created!
# 
# Form ID: xyz789-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 
# Use in your code:
# 
#   import { useTownHallForm } from '@townhall-gg/react'
# 
#   const form = useTownHallForm('xyz789-xxxx-xxxx-xxxx-xxxxxxxxxxxx')

Viewing Submissions

View recent form submissions:

bash

# Interactive form selection
townhall submissions

# Or specify a form ID
townhall submissions abc123-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Limit results
townhall submissions --limit 5

# Output:
# 📬 Recent Submissions (5)
# 
# ─── 1 ───────────────────────────────
# ID:   sub_abc123
# Date: 1/8/2026, 3:45:00 PM
# Data:
#   name: John Doe
#   email: john@example.com
#   message: Hello there!
# 
# ─── 2 ───────────────────────────────
# ...

Project Setup

Initialize TownHall in your project to create a configuration file:

bash

townhall init

# Output:
# 🏛️  Initialize TownHall
# 
# ? Select an existing form? Yes
# ? Choose form: Contact Form
# 
# ✓ Created .townhallrc
# 
# Next steps:
#   npm install @townhall-gg/react

This creates a .townhallrc file in your project:

json

{
  "formId": "your-form-id"
}

Configuration Location

The CLI stores configuration in your system's app data directory:

Windows: %APPDATA%\townhall-nodejs\Config\config.json
macOS: ~/Library/Preferences/townhall-nodejs/config.json
Linux: ~/.config/townhall-nodejs/config.json

Resources

GitHub Repository npm Package