CLI Reference

The cstar CLI is a developer tool for local webhook testing, log streaming, API key management, and AI agent integration via MCP server mode.

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

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

Forward webhook events to a local URL. Perfect for development.

# 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

cstar search

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 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)

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"}'

MCP Tools

The following community tools are available in MCP server mode:

cstar_list_community_posts List/filter community posts

cstar_get_community_post Get a single post by ID

cstar_list_community_topics List discussion topics

cstar_create_community_post Create a new post