Skip to main content

CLI Reference

cstar is the local-dev surface. Forward webhooks to localhost. Tail request logs. Rotate API keys. Run as an MCP server so Claude Code or Cursor can poke at your support data. Stripe-style ergonomics, cStar bones.

Installation

npm install -g @cstar.help/cli
# or run without installing
npx @cstar.help/cli <command>

Authentication

# Login with your API key
cstar login --api-key sk_test_your_key_here

# Check current status
cstar status

# Logout
cstar logout

Credentials are stored at ~/.cstar/config.json with 0600 permissions.

Global Flags

--json Structured JSON output (stdout=data, stderr=status)
--api-key <key> Override stored API key for this command
--base-url <url> Override API URL (default: https://www.cstar.help)
--no-color Disable colored output

Commands

cstar login

Validate and store API key credentials.

cstar login --api-key sk_test_your_key_here

cstar logout

Remove stored credentials.

cstar logout

cstar status

Show current team, environment, key type, and rate limit info.

cstar status
cstar status --json

cstar events

List available webhook event types. Filter by category.

cstar events
cstar events --category tickets
cstar events --category gamification --json

cstar keys

Manage API keys for your team.

# List all keys
cstar keys list
cstar keys list --environment live

# Create a new key
cstar keys create --name "Production" --type secret --environment live

# Revoke a key
cstar keys revoke key_id_here

cstar listen

Tunnel production webhook events to a local URL. No ngrok required.

# Forward to default (localhost:3000/api/webhooks)
cstar listen

# Forward to a custom URL
cstar listen --forward-to http://localhost:8080/webhook

# Filter to specific events
cstar listen --events ticket.created,ticket.closed
How it works: The CLI registers a listener with cStar, opens an SSE stream, and forwards each received event to your local URL with proper signing headers. Press Ctrl+C for a clean disconnect.

cstar trigger

Fire a test webhook event to all active webhooks and CLI listeners.

cstar trigger ticket.created
cstar trigger boss.spawned --json

cstar logs

View API request logs for your team.

# Recent logs (last hour, 20 results)
cstar logs

# Filter logs
cstar logs --method POST --status 4xx --since 24h

# Real-time streaming
cstar logs --tail

cstar members

List and inspect team members.

cstar members list
cstar members list --role agent
cstar members get mem_abc123

cstar analytics

View team analytics overview with ticket, customer, and CSAT metrics.

cstar analytics
cstar analytics --period month
cstar analytics --json

Search across tickets, customers, and articles.

cstar search "billing issue"
cstar search "login" --types tickets,customers
cstar search "password" --limit 5

cstar game

View game system data — boss battles, leaderboards, achievements, quests, and player stats.

cstar game boss status
cstar game leaderboard --period weekly
cstar game achievements --user-id usr_abc --unlocked
cstar game quests --user-id usr_abc
cstar game player --user-id usr_abc

cstar doctor

Diagnose your local cStar setup — config file, credentials, environments, and connectivity. Runs automatically on first error.

cstar doctor

cstar env

Manage multiple named environments (dev, staging, prod). Each environment stores its own API key, team ID, and base URL — switch between them without re-running cstar login.

# List all environments
cstar env list

# Print the active environment
cstar env current

# Add a new environment
cstar env add staging \
  --api-key sk_test_xxx \
  --team-id tm_abc \
  --team-name "Acme Staging"

# Switch active environment
cstar env switch staging

# Remove an environment
cstar env remove staging

cstar seed

Populate your team with realistic sample data for development. Templates include helpdesk (default) and others; --demo creates a richer dataset.

# Default helpdesk template (5 categories, ~12 articles, 3 customers, 5 tickets)
cstar seed

# Pick a template
cstar seed --template helpdesk

# Larger demo dataset
cstar seed --demo

# Wipe seeded data first
cstar seed --clean

# Apply config from cstar.yaml (combine with --diff to dry-run)
cstar seed --from cstar.yaml --diff

cstar create

Scaffold a starter app wired to your team — pick a dashboard or a help center.

# Custom support dashboard (default)
cstar create --type dashboard --dir my-dashboard

# Public help center
cstar create --type help-center --dir my-help-center

# Skip dependency install
cstar create --skip-install

cstar tutorial

Run interactive tutorials in your terminal — each builds something real with your team data.

# List available tutorials
cstar tutorial list

# Start a tutorial (e.g. real-time inbox, chat widget, knowledge base)
cstar tutorial start realtime-inbox

cstar automations

Manage automation rules — declarative triggers that run when a webhook event fires. Each rule has a trigger event, optional conditions, and one or more actions.

# List rules (filter by enabled or trigger event)
cstar automations list
cstar automations list --enabled
cstar automations list --trigger ticket.created

# Create a rule (name + trigger required; load actions from a JSON file)
cstar automations create \
  --name "Auto-tag VIPs" \
  --trigger customer.created \
  --from-file rules/vip-tag.json

# Enable / disable a rule
cstar automations toggle aut_abc123 --enable
cstar automations toggle aut_abc123 --disable

# Test a rule against an existing ticket (no side effects in test mode)
cstar automations test aut_abc123 --ticket tkt_abc

# Inspect recent rule executions
cstar automations executions
cstar automations executions aut_abc123 --limit 50

# Delete a rule
cstar automations delete aut_abc123

cstar config

Manage team configuration as code. Export the live config to cstar.yaml, version it alongside your application, and apply changes from CI.

# Export the current team config
cstar config export > cstar.yaml

# Apply config from a file
cstar config apply cstar.yaml

# Dry-run: show what would change without applying
cstar config apply cstar.yaml --diff

cstar mcp-server

Run as an MCP (Model Context Protocol) server for AI agents like Claude Code. Uses JSON-RPC over stdin/stdout.

cstar mcp-server --stdio

MCP Server Configuration

Add to your Claude Code or MCP-compatible AI configuration.

claude_desktop_config.json 
{
  "mcpServers": {
    "cstar": {
      "command": "npx",
      "args": ["@cstar.help/cli", "mcp-server", "--stdio"]
    }
  }
}

Available MCP Tools

cstar_list_tickets List tickets with filters (status, priority, search)
cstar_get_ticket Get ticket by ID with messages
cstar_create_ticket Create a new support ticket
cstar_list_customers List customers with optional search
cstar_get_customer Get customer by ID
cstar_list_articles List knowledge base articles
cstar_trigger_webhook Fire a test webhook event
cstar_get_status Get auth status and team info
cstar_list_events List available webhook event types
cstar_list_members List team members with roles and levels
cstar_search Search across tickets, customers, and articles
cstar_analytics Get team analytics overview
cstar_boss_status Get current boss battle state
cstar_leaderboard Get team leaderboard rankings
cstar_player_stats Get player stats (level, XP, streak)
cstar_list_community_posts List/filter community posts
cstar_get_community_post Get a single community post by ID
cstar_list_community_topics List discussion topics
cstar_create_community_post Create a new community post

JSON Output

All commands support --json for structured output.

Success 
{ "success": true, "data": { ... } }
Error 
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "suggestion": "Check the ID and try again"
  }
}

Exit Codes

0 Success
1 Error (API error, auth failure, etc.)
2 Usage error (missing required arguments)

Community Commands

Manage community posts and topics from the command line.

List Posts

# List all community posts
cstar community list

# Filter by topic, status, or sort order
cstar community list --topic topic_abc --status open --sort votes

# JSON output for scripting
cstar community list --json

Get Post

# Get a single post by ID
cstar community get post_abc123

List Topics

cstar community topics

Create Post

cstar community create \
  --title "Tutorial Video" \
  --topic-id topic_abc \
  --body "Check out this walkthrough" \
  --custom-fields '{"video_url": "https://youtube.com/watch?v=abc"}'

Community is also exposed in MCP server mode — see the four cstar_*_community_* tools in the main MCP tools table above.