Run your events from the terminal

1. 1

   Install it

   One npm install, on macOS, Linux or Windows. Node 20 or newer.

   Terminal Copy

   $ npm install -g ticketfairy
   $ ticketfairy --version

2. 2

   Sign in

   Opens your browser and handles two-factor sign-in. On a server, set a Personal Access Token instead.

   Terminal Copy

   $ ticketfairy login
   # on a server or in CI, use a token instead
   $ export TICKET_FAIRY_API_KEY="…"

3. 3

   Pick your brand and go

   Set the brand once for this machine, then every command works against it.

   Terminal Copy

   $ 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. Named profiles let one machine keep separate sign-ins for separate environments.

• 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 write 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 Webhooks scoped to 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 banking data for brands with Vault access. Ask your account manager about access for your brand.

#!/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 becomes 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 organisation's retention schedule.