--- title: "Ticket Fairy CLI | Run Your Events From the Terminal" description: "Automate your event setup, exports and reporting from the command line with the Ticket Fairy CLI. Install with npm." canonical: "https://www.ticketfairy.com/cli" --- Ticket Fairy CLI # Run your events from the terminal Script the event operations you repeat in the dashboard. With `ticketfairy`, you manage events, tickets and orders, read customer and Vault data, and export orders and customers from the command line, a scheduled job or an AI assistant. 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 and MIT licensed. You need Node 20 or newer. Terminal ```text # install once $ npm install -g ticketfairy # sign in with your Ticket Fairy account $ ticketfairy login # list events for the active brand $ 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. You see your own events and brands, within your permissions. ## Repeat event setup and reports from the terminal You can use the dashboard for a one-off change. You can also use the CLI when you need the same setup across several events, a report on a schedule, or an action another system starts. ### Set up events without repeating yourself Clone a previous event, create events and ticket types from JSON or YAML files, or send invitations from a CSV list. Event and ticket-type create and update commands accept `--from-file`, and invitations accept `--from-csv`. Keep the source file and run it again when you need it. ### Pull a sales summary on a schedule Save an event's sales figures as JSON for a nightly report or monitoring job. Skip the dashboard copy and paste, and let the scheduled command run without a Monday reminder. ### 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. You can call the CLI safely from any script or pipeline, because its JSON output is stable and its exit codes are documented. ### Let an AI assistant do the work safely Claude Code and other assistants can read and change your events inside guardrails you set, through the Model Context Protocol server that the same tool starts, instead of driving a browser. ## Set up the CLI You request no API keys, configure no integration and need no separate account, because the CLI signs in as you. 1. ### Install it Install with one npm command on macOS, Linux or Windows. You need Node 20 or newer. Terminal ```sh $ npm install -g ticketfairy $ ticketfairy --version ``` 2. ### Sign in Your browser opens for you to sign in, including two-factor sign-in. On a server, set a Personal Access Token instead. Terminal ```sh $ 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, and every command uses it from then on. Terminal ```sh $ ticketfairy brand list $ ticketfairy brand use 12345 $ ticketfairy event list ``` **Your token is never one of those settings.** Signing in stores it in your operating system's keychain where available, or in the protected credentials file otherwise. A server can read it from `TICKET_FAIRY_API_KEY`. A project `.ticketfairyrc` can override the active profile and API address, so review a project's settings before you use them. If the same setting appears more than once, a flag wins over an environment variable, which wins over the project file, which wins over your global config. With named profiles, you keep separate sign-ins on one machine for separate environments. ## Event operations and terminal tools You can manage events, tickets, orders and customers with the operational groups, and automation, updates and extensions with the rest. Run any command with `--help` for its flags and examples. Commands that read Ticket Fairy data support `--output json`. - `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 and select your brands, see the available series, venue, country and city filters, or use brand stats for whole-brand geographic and demographic insights. Geographic reports can be filtered by event, series, venue, country or city. - `ticketfairy account` Start identity verification when you need it before publishing. - `ticketfairy config` Read and change the settings this machine uses: brand, output format, API base, profiles. - `ticketfairy event` Create, update, publish, unpublish, postpone, disclose a postponed date, 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, approve pending orders and export. - `ticketfairy customer` Search, list, 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` Manage webhooks for an event, a brand or a tour. - `ticketfairy vault` Read-only view of Vault: account, balance, cards, transactions, transfers and beneficiaries. - `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 help` Show help for the CLI or for a specific command. - `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. - `ticketfairy plugins` Install, list, link and remove community-built command groups. Only install plugins from sources you trust. - `ticketfairy autocomplete` Set up command completion for Bash, Zsh or PowerShell. - `ticketfairy update` Update the CLI through the same installation method that installed it. **Vault commands are invitation only.** They return read-only Vault account data for brands with Vault access. Ask your account manager about access for your brand. ## Built for scheduled jobs You can run the CLI in a nightly job with predictable output, clear errors, up to three retries and dry runs. You can add non-interactive mode so a missing value fails instead of waiting for an answer. ### Data on stdout, everything else on stderr Commands that return Ticket Fairy data print a readable table in a terminal and switch to JSON when output is piped. Progress and logs go to stderr, so what you pipe is always pure data. ### Exit codes for Ticket Fairy commands Ticket Fairy data and action commands use 0 for success, 1 for an unexpected error, 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, where useful, a hint. ### Safe retries, with a clear boundary Supported creates and PATCH updates carry a generated idempotency key, so a retry within one CLI run does not repeat the change. For a POST or PATCH script you may run again, pass your own `--idempotency-key`. For 24 hours, repeating the same request with the same key returns the original response. PUT updates, deletes and token minting or rotation are not replayed. ### See the request before you send it `--dry-run` prints exactly what would be sent and stops there, so you can review a bulk change before it touches a single order. nightly-sales-report.sh ```bash #!/usr/bin/env bash set -euo pipefail umask 077 EVENT=evt_9f21 # keep a dated snapshot of the event's sales summary 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 ends with exit code 2 rather than waiting for input. Then the job runs unattended, and a failure exits with a code your scheduler can act on. If you schedule an export that contains buyer data, keep it in approved access-controlled storage and delete it on your organization's retention schedule. ## A token cannot exceed your permissions The CLI signs in as you, not as an application with extra powers. Your Personal Access Token carries your dashboard role and your access to brands and events. It cannot grant itself permission to issue refunds or reach another brand's data. You name each token, so you can tell the deploy bot from your laptop. Each token expires within a year. You can rotate one 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 you can revoke one the moment a laptop goes missing. You can give each automation its own named token, a useful description and an expiry that matches the job. You can then review or revoke that access without disrupting your other work. Terminal ```sh # 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 # review the tokens that are still active $ ticketfairy auth tokens list ``` ## The same tool your AI assistant can use You can let Claude Code, Cursor and other assistants work with your events through structured tools instead of guesswork. `ticketfairy mcp` starts the CLI's Model Context Protocol server, with the same sign-in and permissions, and a read-only mode to start with. [How the MCP server works](https://www.ticketfairy.com/mcp-server) [Meet Fai, your AI teammate](https://www.ticketfairy.com/event-ticketing/ticket-fairy-ai) For a focused read, [choose the hosted event review, sales and orders, or show day App](https://www.ticketfairy.com/mcp-server#focused-apps). ## Questions about the CLI ### Do I need to be a developer to use the Ticket Fairy CLI? No, but it helps to be comfortable in a terminal. You can also do core event, ticket, order and customer work in the dashboard. The CLI adds repeatable commands, scheduled reports, direct API access and terminal helpers such as updates and shell completion. ### What can the CLI do that the dashboard cannot? It uses the same account, permissions and API for your event operations, then adds files you can keep, structured output, pipelines, plugins and a direct API command. Some connected-provider sign-ins still stay in the browser. The practical difference is repeatability: a command can run tomorrow, in a pipeline or against another event. ### Is it safe to give a script access to my account? Your Personal Access Token carries the same role and brand permissions you have in the dashboard, so it cannot give a script any extra access. 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. ### Can I use it in CI, on a server, or in Docker? Yes. Set `TICKET_FAIRY_API_KEY` and the CLI never prompts you to sign in. Add `--non-interactive` and a missing input ends with exit code 2 instead of a prompt that waits for input. ### What does the MCP server have to do with the CLI? It is the same package. `ticketfairy mcp` starts a Model Context Protocol server on your own machine so an AI assistant can use selected commands as structured tools, with the same sign-in and the same permissions. ### Can an update break a script I already rely on? Command names and JSON fields can change between releases, so pin a version in scripts and pipelines. With a pinned version, you upgrade when it suits you, and a new release never changes a pipeline you depend on. See how the Ticket Fairy [online ticketing system](https://www.ticketfairy.com/event-ticketing/) helps you sell more tickets, with every feature, the pricing and the support you get. ## Further Reading [**MCP server for your account** Let the AI assistant you use manage your own events.](https://www.ticketfairy.com/mcp-server) [**Ticket Fairy API** Create events, read sales and copy an event's setup.](https://www.ticketfairy.com/developers/organiser-api) [**Authentication** Personal Access Tokens, agent approval and OAuth.](https://www.ticketfairy.com/developers/authentication) ## Put repeatable event admin on a schedule Install the CLI, sign in with your existing account, and automate recurring setup and reports. [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). The Ticket Fairy, Inc. is a fintech company and technology platform. The Ticket Fairy, Inc. is not a bank, financial institution, or regulated financial services provider. Vault banking services are provided through regulated banking partners. --- 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)