Ticket Fairy CLI

Product Introduction

1. Definition: The Ticket Fairy CLI is a command-line interface tool, specifically a Node.js package, that provides programmatic access to the Ticket Fairy event management and ticketing platform. It is a developer-focused automation layer that translates dashboard operations into scriptable commands.
2. Core Value Proposition: It exists to automate repetitive event administration tasks, enable reliable data exports for reporting, and integrate Ticket Fairy's functionality into existing DevOps pipelines and third-party systems, thereby eliminating manual, error-prone dashboard work.

Main Features

1. Comprehensive Event & Ticket Management: The CLI provides commands for the entire event lifecycle. This includes creating, cloning, updating, publishing, and canceling events (ticketfairy event). It also manages ticket types (ticketfairy ticket), add-ons (ticketfairy addon), and table reservations (ticketfairy table). Commands like event clone and --from-file flags allow for templating and bulk operations, enabling efficient setup of recurring or similar events.
2. Structured Data Export & Reporting: A core feature is the ability to programmatically extract data. Commands like ticketfairy order export and ticketfairy customer export output directly to CSV or JSON formats. The ticketfairy event stats command provides sales summaries. This feature is designed for unattended operation, with output to stdout and logs/errors to stderr, making it safe for cron jobs or CI/CD pipelines to pipe data into data warehouses or reporting tools.
3. Secure, Person-Centric Authentication & Authorization: Instead of generic API keys, the CLI uses Personal Access Tokens scoped to an individual user's existing Ticket Fairy account. This means the token inherits the user's exact permissions, roles, and brand/event access. Features like token rotation (with up to 7-day overlap), expiration (up to 1 year), and audit logging (ticketfairy auth tokens list) ensure security and accountability, as all actions are recorded against the human token owner.
4. Model Context Protocol (MCP) Server Integration: The ticketfairy mcp command boots a local MCP server, exposing the CLI's capabilities as structured tools for AI assistants like Claude Code or Cursor. This allows AI agents to perform authorized, guardrailed operations (e.g., checking event stats, drafting ticket types) using natural language, bridging the gap between conversational AI and precise platform automation.

Problems Solved

1. Pain Point: Manual, repetitive administrative work in a web dashboard is slow, not auditable, and impossible to automate. This includes cloning event setups, applying bulk promo codes, and generating daily sales reports.
2. Target Audience: Event Operations Managers & Producers who need to automate event setup and reporting; Developers & DevOps Engineers at event companies who integrate ticketing data into internal systems (CRM, analytics, Slack); Data Analysts requiring clean, scheduled data exports; Promoters & Venue Managers running multi-event series who need consistency.
3. Use Cases: Scheduled Reporting: A nightly cron job exports the previous day's orders and event stats to a cloud storage bucket. Event Series Setup: A script reads a YAML config file to clone a template event, create 10 tiered ticket types, and upload a promo code list for a season of shows. CI/CD Integration: A deployment pipeline triggers a script to update event descriptions and on-sale times across multiple events as part of a marketing campaign rollout. AI-Powered Assistance: A promoter uses an AI assistant via MCP to quickly check ticket sales across all draft events and generate a summary report.

Unique Advantages

1. Differentiation: Unlike using the raw Ticket Fairy API directly, the CLI handles authentication (via OS keychain or env var), retry logic, idempotency keys, and output formatting (table/JSON/CSV) out-of-the-box. Compared to dashboard-only usage, it provides repeatability, scriptability, and integration capabilities that the GUI cannot.
2. Key Innovation: Its idempotency-by-default design for state-changing commands (using or allowing --idempotency-key) prevents duplicate charges or events in retry scenarios. Furthermore, its dual-purpose output (human-readable tables in TTY, pure JSON/CSV when piped) and predictable exit codes make it uniquely reliable for automation, a feature not common in many CLIs.

Frequently Asked Questions (FAQ)

1. Is the Ticket Fairy CLI suitable for users without coding experience? While the CLI is designed for terminal and scripting use, its commands are structured and well-documented. Non-developers comfortable with basic command-line operations can use it for tasks like exports. However, for advanced automation and integration, some scripting knowledge is beneficial. All functionality remains available in the user-friendly dashboard.
2. How does authentication and security work for unattended scripts? For scripts and servers, you use a Personal Access Token set in the TICKET_FAIRY_API_KEY environment variable. This token is tied to a user account, inheriting its permissions, and can be scoped. It is never stored in plain config files. The CLI also supports a --non-interactive flag for scripts to fail cleanly instead of prompting for input.
3. Can I use the CLI to manage multiple Ticket Fairy brands or accounts? Yes. The ticketfairy brand command lets you list and switch the active brand. Furthermore, the tool supports named configuration profiles, allowing you to maintain separate settings (including authentication for different accounts or environments) on a single machine.
4. What guarantees does the CLI provide for safe automation in production? It provides four key guarantees: 1) Separation of data (stdout) from logs (stderr), 2) Consistent, documented exit codes for error handling, 3) Idempotency keys on create/update calls to prevent duplicates on retry, and 4) A --dry-run flag to preview API payloads before execution.
5. What is the relationship between the ticketfairy CLI and the ticketfairy mcp server? They are the same package. The standard CLI is for direct human or script use. The mcp command starts a Model Context Protocol server that exposes the CLI's capabilities as tools an AI assistant can use. Both modes share the same authentication, permissions, and command logic.