# Ticket Fairy CLI | Run Your Events From the Terminal Ticket Fairy CLI # Run your events from the terminal `ticketfairy` drives events, tickets, orders, customers and payouts from your shell, your scheduled jobs, or an AI assistant. Everything you can do in the dashboard, you can script. Install it in one command, sign in with the account you already have, and start with `ticketfairy event list`. [Install the CLI](https://www.npmjs.com/package/ticketfairy) [See what it can do](#commands) Free with your Ticket Fairy account. MIT licensed. Requires Node 20 or newer. Terminal ``` # install once $ npm install -g ticketfairy # sign in with your Ticket Fairy account $ ticketfairy login # and you are working $ ticketfairy event list id name starts status venue evt_9f21 Summer Fest 2027 2027-07-16 live Victoria Park evt_7b30 Warehouse Sessions #14 2027-03-04 live Unit 9 evt_5c02 Sunset Rooftop Series 2027-05-22 draft The Deck ``` Sample output. Your events, your brands, your permissions. Version 0.x, in active development. Pin a version in scripts. ## The work the dashboard makes slow Clicking is the right tool for a one-off change. It is the wrong tool for the same change made forty times, for a report someone has to remember to run, and for anything another system has to trigger on its own. ### Set up events without repeating yourself Clone last year's event, create a season of ticket types, or load a ten-thousand-row promo code list from a file. Every create and update command accepts `--from-file`, so the payload is a file you keep and run again next time. ### Pull sales data on a schedule Export orders and customers as CSV or JSON straight into a spreadsheet, a warehouse, or a nightly report. No copy and paste out of a dashboard screen, and no one has to remember to do it on Monday. ### Wire Ticket Fairy into the tools you already run Post an on-sale alert into Slack, sync attendees into your own CRM, or let a webhook start a script of your own. Stable JSON output and documented exit codes make the CLI safe to call from any script or pipeline. ### Let an AI assistant do the work safely The same tool boots a Model Context Protocol server, so Claude Code and other assistants can read and change your events inside guardrails you set, not by driving a browser. ## Working in three commands No API keys to request, no integration to configure, no separate account. The CLI signs in as you. 1. ### Install it One npm install, on macOS, Linux or Windows. Node 20 or newer. Terminal ``` $ npm install -g ticketfairy $ ticketfairy --version ``` 2. ### Sign in Opens your browser and handles two-factor sign-in. On a server, set a Personal Access Token instead. Terminal ``` $ ticketfairy login # on a server or in CI, use a token instead $ export TICKET_FAIRY_API_KEY="…" ``` 3. ### Pick your brand and go Set the brand once for this machine, then every command works against it. Terminal ``` $ ticketfairy brand list $ ticketfairy brand use 12345 $ ticketfairy event list ``` **Your token is never one of those settings.** Signing in puts it in your operating system's keychain, and a server reads it from `TICKET_FAIRY_API_KEY`. What the config files hold is which brand, output format and API address to use, so a `.ticketfairyrc` is safe to commit alongside your project. Settings layer in a predictable order: flags beat environment variables, which beat that project file, which beats your global config. Named profiles let one machine keep separate sign-ins for separate environments. ## Every part of your event operation The command groups cover the same ground as the dashboard. Run any of them with `--help` for the full list of flags and examples, and expect the same JSON from all of them. - `ticketfairy init` One-shot setup: log in, pick the active brand, choose a default output format. - `ticketfairy auth` Log in and out, check who you are, and manage Personal Access Tokens. - `ticketfairy brand` List your brands and set the one every other command works against. - `ticketfairy account` Start identity verification, where the account and the event need it before publishing. - `ticketfairy config` Read and write the settings this machine uses: brand, output format, API base, profiles. - `ticketfairy event` Create, update, publish, postpone, cancel, reinstate, clone, delete, and read stats. - `ticketfairy ticket` Ticket types for an event: list, create, update, delete. - `ticketfairy addon` Add-ons such as parking, merchandise and VIP perks, including grouping and order. - `ticketfairy table` Table types for venue and club events with table service. - `ticketfairy order` List, inspect, refund, cancel free orders, mark as paid, and export. - `ticketfairy customer` List, search, inspect and export customers. - `ticketfairy invitation` Send, resend and cancel invitations, including from a CSV file. - `ticketfairy promotion` Create and manage promo codes. - `ticketfairy messaging` List and send messaging campaigns. - `ticketfairy checkin` Read live check-in status for an event. - `ticketfairy team` Invite team members, change their role, and revoke access. - `ticketfairy tour` Group events into a single brandable run, and manage its members. - `ticketfairy webhook` Webhooks scoped to an event, a brand or a tour. - `ticketfairy vault` Read-only view of Vault banking: account, balance, cards, transactions, transfers. - `ticketfairy asset` Upload artwork and files, and get back the CDN URL to use in a payload. - `ticketfairy api` Call any Ticket Fairy API endpoint directly, with auth and retries attached. - `ticketfairy manifest` Print the whole command tree as JSON, so a script or an agent can discover it. - `ticketfairy mcp` Start the built-in Model Context Protocol server for AI assistants. **Vault commands are invitation only.** They work for brands enrolled in the Ticket Fairy Card programme and return nothing for everyone else. Ask your account manager if you want in. ## Built to be run by something other than a person A command you can only run by hand is a command you will run once. These four guarantees are what make it safe to put in a nightly job. ### Data on stdout, everything else on stderr Commands print a readable table in a terminal and switch to JSON the moment output is piped. Progress and logs go to stderr, so what you pipe is always pure data. ### Exit codes you can branch on 0 for success, 2 for a usage mistake, 3 for a network failure, 4 for authentication, 5 for not found, 6 for a conflict, 7 for rate limiting. Errors carry a stable code, a message and a hint. ### Retries that cannot double-charge Creating and updating carries an idempotency key. Pass your own with `--idempotency-key` and re-running the same command is a no-op instead of a second refund or a duplicate event. Two things sit outside it: a delete is not replayed, so a retry answers not-found rather than success, and minting or rotating a token is never replayed because its answer carries the secret. ### See the request before you send it `--dry-run` prints exactly what would be sent and stops there, so a bulk change can be reviewed before it touches a single order. nightly-sales-report.sh ``` #!/usr/bin/env bash set -euo pipefail EVENT=evt_9f21 # drop today's orders into a dated CSV, keeping the last good one # until this run has actually written a new one ticketfairy order export "$EVENT" --output csv > "orders.part" mv "orders.part" "orders-$(date +%F).csv" # keep a dated snapshot of the sales summary beside it ticketfairy event stats "$EVENT" --output json > "stats.part" mv "stats.part" "stats-$(date +%F).json" ``` Set `TICKET_FAIRY_API_KEY` in the job's environment and add `--non-interactive` so a missing input becomes exit code 2 rather than a question nobody is there to answer. Then it runs unattended, and a failure exits with a code your scheduler can act on. ## A token can never do more than the person who made it The CLI signs in as a real person, not as an application with its own powers. A Personal Access Token carries exactly the role and the brand or event scope that person has in the dashboard, so a script written by a door supervisor cannot issue refunds, and one written by a promoter cannot reach another brand's data. Tokens are named, so you can tell the deploy bot from your laptop. They expire, up to a year. They can be rotated with an overlap of up to seven days, so a pipeline keeps running while you swap the value over. The overlap ends when the old token would have expired anyway, so rotate before its last week rather than during it. And they can be revoked the moment a laptop goes missing. Wherever Ticket Fairy keeps a history of a record, a change made with a token is attributed to that person in it, exactly as if they had clicked it themselves. Orders, refunds and ticket changes carry that record. Terminal ``` # mint a token for a pipeline, shown once $ ticketfairy auth tokens create "CI deploy bot" --expires-in 30d # swap it out without breaking the pipeline: up to 7 days of overlap $ ticketfairy auth tokens rotate 42 # audit which tokens are still in use $ ticketfairy auth tokens list ``` ## The same tool your AI assistant can use `ticketfairy mcp` turns the CLI into a Model Context Protocol server, so Claude Code, Cursor and other assistants work with your events through structured tools instead of guesswork. Same sign-in, same permissions, and a read-only mode to start with. [How the MCP server works](https://www.ticketfairy.com/mcp-server) [Meet Fai, the AI co-pilot](https://www.ticketfairy.com/event-ticketing/ticket-fairy-ai) ## Questions people ask first No, but it helps to be comfortable in a terminal. If you would rather click, everything the CLI does is also in the dashboard. The CLI exists for the jobs clicking makes slow: repeating the same setup, exporting on a schedule, and connecting Ticket Fairy to your own tools. It drives the same events, orders and API operations through the same API, so the day-to-day work you do in the dashboard you can script here. A few things stay in the browser, such as signing in to a connected provider. What the CLI adds is repeatability: a command can run again tomorrow, in a pipeline, or against a second event. A Personal Access Token is scoped to one person and carries exactly the role and brand permissions that person has in the dashboard, so a script can never do more than the human who created it. Tokens are named, expire (up to a year), can be rotated with an overlap of up to seven days, so a pipeline keeps running while you swap the value over. The overlap never outlasts the old token's own expiry, so rotate before the last week rather than during it. Yes. Set `TICKET_FAIRY_API_KEY` and the CLI never prompts for anything. Add `--non-interactive` and a missing input becomes exit code 2 instead of a question nobody is there to answer. It is the same package. `ticketfairy mcp` starts a Model Context Protocol server on your own machine so an AI assistant can use the same commands as structured tools, with the same sign-in and the same permissions. Yes, with one precaution: pin a version in scripts and pipelines. Command names and JSON fields can still change between minor releases before 1.0, and a pinned version means an upstream release can never surprise a pipeline you depend on. Ticket Fairy in full: [online ticketing system](https://www.ticketfairy.com/event-ticketing/), with the features, pricing and support behind this page. ## Further Reading [**Best Event Ticketing Software Compared**](https://www.ticketfairy.com/blog/the-best-event-ticketing-software-of-2023-price-and-feature-comparison) [**Early Bird & Tiered Pricing Strategies**](https://www.ticketfairy.com/blog/tiered-pricing-and-early-bird-strategies-for-festivals) [**Using Ticketing Data to Improve Your Events**](https://www.ticketfairy.com/blog/how-to-use-ticketing-data-and-analytics-to-improve-your-festival) ## Put the repetitive half of your event admin on a schedule Install the CLI, sign in with the account you already have, and let a script do the parts nobody enjoys doing twice. [Install the CLI](https://www.npmjs.com/package/ticketfairy) [Create a free account](https://manage.ticketfairy.com/welcome) [Book a demo](https://www.ticketfairy.com/event-ticketing/book-a-demo) Questions about scripting your setup? Email [support@theticketfairy.com](mailto:support@theticketfairy.com). --- This page is on Ticket Fairy, a ticketing, marketing and operations platform for live events and the venues that host them: festivals, club nights, concerts, conferences and tours, and night clubs, beach clubs and concert venues. It grows revenue with fan rewards that turn an audience into a sales channel, and runs the money side with payments and payouts, Vault business banking, and working capital advanced against ticket sales. [How Ticket Fairy ticketing works](https://www.ticketfairy.com/event-ticketing) · [Ticket Fairy for AI assistants](https://www.ticketfairy.com/llms.txt)