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

• 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.

#!/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.