Ticket Fairy CLI

ticketfairy drives the entire Ticket Fairy admin surface — events, tickets, orders, customers, payouts — from your shell, your CI pipelines, or an AI agent. Every operation you can do in the dashboard at manage.ticketfairy.com is scriptable here, with stable JSON output and predictable exit codes.

Status: alpha (v0.x). The CLI is in active development. Command surfaces and JSON schemas may change between minor releases until v1.0 — see Stability for how to insulate scripts and CI.

Quickstart

# install (Node ≥20 required — see Prerequisites)
npm install -g ticketfairy

# log in once on your laptop (opens a browser, handles 2FA)
ticketfairy login

# or, in CI / agents, use a Personal Access Token
export TICKET_FAIRY_API_KEY="…"

# do things
ticketfairy event list
ticketfairy order export evt_123 --output csv > orders.csv
ticketfairy invitation send evt_123 --from-csv vips.csv --ticket-type tt_123

Why a CLI

The dashboard is great for one-off changes, but anyone running events at scale ends up wanting to:

• Script repetitive setup (cloning an event, bulk-creating ticket types, dropping a 10k-row promo code list).
• Pull data into spreadsheets / dashboards / data warehouses on a schedule.
• Wire Ticket Fairy into other tools (Slack alerts, Zapier-style automations, custom CRMs).
• Let an AI agent (Claude Code, Cursor, etc.) read and write Ticket Fairy state safely.

ticketfairy is the answer to all of those — every operation in the dashboard, scriptable, with stable JSON output and predictable exit codes.

Prerequisites

• Node.js 20 or newer (node -v). The CLI is published to npm as an ES module package and uses Node-20-only APIs.
• npm in PATH. Required by every install path — the Homebrew formula and the shell installer both call npm install under the hood. If you already have Node, you already have npm.

If you need to manage multiple Node versions, fnm and nvm both work fine.

Installation

npm (recommended)

npm install -g ticketfairy
ticketfairy --version

Homebrew

brew install theticketfairy/tap/ticketfairy
ticketfairy --version

The Homebrew tap pulls the latest npm tarball — same code, same versioning.

Shell installer

curl -fsSL https://cli.theticketfairy.com/install.sh | sh

Installs the CLI into ~/.ticketfairy/ (its binary lands in ~/.ticketfairy/bin) and prints the exact PATH line to add to your shell profile. Requires Node ≥20 and npm available in PATH. Good for environments where you don't want to run npm -g against your system Node (no sudo needed). If the URL isn't reachable yet, use the npm install above — it's the same package.

Optional: shorter alias

ticketfairy is the canonical name on purpose — tf collides with terraform on a lot of developer machines (alias tf=terraform is a common dotfile). If you'd rather type something shorter on your own laptop:

echo 'alias tf=ticketfairy' >> ~/.zshrc       # or ~/.bashrc
exec $SHELL -l                                 # reload
tf event list                                  # same as `ticketfairy event list`

Scripts, Makefiles, and CI workflows should always use the full ticketfairy name — aliases don't carry across machines.

Authentication

Three credential sources, resolved in this order:

| Mode | When to use | Setup | |------|-------------|-------| | TICKET_FAIRY_API_KEY env var | CI, agents, headless servers | Mint a Personal Access Token in the dashboard (Account Settings → Personal Access Tokens) or via ticketfairy auth tokens create, then export TICKET_FAIRY_API_KEY=… | | Browser OAuth (ticketfairy login) | Your laptop, default for humans | Opens a browser, you log in (2FA supported), token stored in your OS keychain | | Email + password (ticketfairy login --password) | Headless hosts without a browser; 2FA must be off | Prompts for credentials interactively |

Tokens are scoped per-user and inherit the same role/permissions as the dashboard session.

Personal Access Tokens from the CLI

Long-lived tokens are full-feature in the CLI — same surface as the dashboard's Account Settings → API Tokens page:

ticketfairy auth tokens list                              # see all your PATs (current row marked ✓)
ticketfairy auth tokens create "CI deploy bot"            # mint a new one — token shown ONCE
ticketfairy auth tokens create "CI" --expires-in 30d      # custom expiry (default 1 year, max 1 year)
ticketfairy auth tokens rotate 42                         # mint fresh + 7-day grace on old (CI keeps working)
ticketfairy auth tokens revoke 42 --force                 # revoke by id (refuses to revoke the active token unless you pass --allow-self-revoke)

auth status reports the active token's name + last-used time, so you can audit dormant tokens at a glance:

$ ticketfairy auth status
authenticated  source  email             pat name        last used            expires
true           env     [email protected]  CI deploy bot   2026-05-09 23:14:07  2027-05-09 10:23:14

Your first 5 minutes

If you'd rather not run individual commands, ticketfairy init is an interactive wizard that does the first three steps below in one go.

Command-by-command, a typical first session looks like this:

# 1. confirm you're signed in and on the right account
ticketfairy auth status

# 2. find your brand(s) and set one as the default for this machine
ticketfairy brand list
ticketfairy brand use 12345

# 3. list events on the active brand
ticketfairy event list

# 4. inspect one event
ticketfairy event get evt_abc123

# 5. download orders as CSV
ticketfairy order export evt_abc123 --output csv > orders.csv

# 6. open the event's dashboard page in your browser (no copy-pasting URLs)
ticketfairy event get evt_abc123 --web

When you're ready to mutate, every create / update command accepts --from-file <path.json> (or --from-yaml), so payloads stay version-controlled and reusable across environments.

Output

By default ticketfairy prints human-readable tables when stdout is a terminal, and switches to JSON when piped or when --output json is set. Every command supports --output {table,json,yaml,csv}.

ticketfairy event list                          # pretty table
ticketfairy event list --output json            # JSON to stdout
ticketfairy event list | jq …                   # pipe → auto-JSON
ticketfairy event list --output csv > out.csv   # CSV

All log/progress output goes to stderr — stdout is always pure data, safe to pipe.

Configuration

Settings are layered; highest priority wins:

1. CLI flags (--brand, --profile, --output, --token, --api-base).
2. Env vars (TICKET_FAIRY_API_KEY, TICKET_FAIRY_API_BASE, TICKET_FAIRY_BRAND, TICKET_FAIRY_PROFILE).
3. Project file: nearest .ticketfairyrc walking up from cwd.
4. Global file: ~/.config/ticketfairy/config.json.

ticketfairy config set brand 12345
ticketfairy config set output json
ticketfairy config list

The CLI talks to production by default. To point it at a different backend (a local dev instance, say), profiles let you keep separate credentials per host:

ticketfairy config set api_base http://localhost:8080 --profile local
ticketfairy login --profile local
ticketfairy event list --profile local

Environment variable reference

| Variable | Effect | |----------|--------| | TICKET_FAIRY_API_KEY | Bearer token (Personal Access Token). Highest-priority credential after --token. | | TICKET_FAIRY_API_BASE | API base URL (same as --api-base). | | TICKET_FAIRY_BRAND | Active brand id (same as --brand). | | TICKET_FAIRY_PROFILE | Named credentials profile (same as --profile). | | TICKET_FAIRY_OUTPUT | Default output format (table, json, yaml, csv). | | TICKET_FAIRY_NON_INTERACTIVE | 1 disables prompts everywhere (same as -y). | | TICKET_FAIRY_TIMEOUT | Per-request timeout in seconds (default 30). | | TICKET_FAIRY_LOG_LEVEL | silent / error / warn / info / debug. | | DEBUG | ticketfairy or ticketfairy:* enables debug logging (same as --debug). | | TICKET_FAIRY_CONFIG_HOME | Overrides the config directory (default ~/.config/ticketfairy, honours XDG_CONFIG_HOME). | | TICKET_FAIRY_DISABLE_KEYCHAIN | 1 skips the OS keychain; tokens go to the credentials file (plaintext, 0600). | | NO_COLOR | Disable all ANSI colour in human-readable output. | | CI | Any value disables interactive prompts. |

Agents

ticketfairy ships an explicit agent contract — see docs/AGENT_GUIDE.md. Hard guarantees:

• --output json on every data-returning command.
• --non-interactive (alias -y) suppresses all prompts; missing required input → exit 2.
• Stable JSON schema per command.
• Documented exit codes (0 ok, 2 usage, 4 auth, 5 not found, …).
• Mutations support --idempotency-key for safe retries.
• ticketfairy <cmd> --help --output json returns the command schema.

Claude Code / Cursor / other MCP clients

The CLI doubles as a Model Context Protocol server. Add to your client's config:

{
  "mcpServers": {
    "ticketfairy": {
      "command": "ticketfairy",
      "args": ["mcp", "--read-only"]
    }
  }
}

Same auth as the interactive CLI (PAT, browser OAuth, or env var) — no separate setup. Tools cover events, tickets, orders, customers, refunds, invitations, addons, promotions, check-in, plus an api passthrough escape hatch for anything not yet wired as a typed tool. --read-only (recommended starting point) exposes read tools only; drop it to enable mutations, where destructive actions additionally require you to approve a prompt in your MCP client before they run. Safety modes, full tool surface, and migration notes from the standalone @theticketfairy/ticketfairy-mcp package: docs/MCP.md.

Top-level commands

ticketfairy init              one-shot setup wizard (login + brand + output format)
ticketfairy auth              login, logout, status, token, tokens (list / create / rotate / revoke)
ticketfairy account           verify  (open Stripe Identity in browser — required before publishing events)
ticketfairy config            get, set, list, unset
ticketfairy brand             list, use, info
ticketfairy event             list, get, create, update, publish, unpublish, cancel, postpone, disclose-date, reinstate, clone, delete, stats
ticketfairy ticket            list, create, update, delete
ticketfairy addon             list, create, update, delete, group, reorder
ticketfairy table             list, create, update
ticketfairy asset             upload  (returns CDN URL for use in event/ticket/addon payloads)
ticketfairy order             list, get, refund, cancel (free orders), mark-paid, export
ticketfairy customer          list, get, search, export
ticketfairy invitation        list, send, resend, cancel
ticketfairy promotion         list, create, update, delete
ticketfairy messaging         list, send
ticketfairy team              list, invite, update, revoke
ticketfairy checkin           status
ticketfairy webhook           list, get, create, update, delete  (event / brand / tour scoped)
ticketfairy tour              list, get, create, update, delete, members  (group events into a single brandable run)
ticketfairy vault             account, balance, cards, transactions, transfers, beneficiaries  (read-only)
ticketfairy api               raw HTTP passthrough — call any endpoint with auth + retry attached
ticketfairy manifest          emit the entire command tree as structured JSON (agent-introspection entry point)
ticketfairy mcp               boot the built-in Model Context Protocol server — see docs/MCP.md
ticketfairy plugins           install, list, link, uninstall (community-built command groups)
ticketfairy autocomplete      bash | zsh | fish completion

ticketfairy vault availability. Vault commands are an invitation-only feature, limited to brands enrolled in the Ticket Fairy Card program. If your brand isn't enrolled, the commands will return an empty/403 response — contact your account manager to opt in. Most users can skip this group.

Useful global flags (every command)

| Flag | What it does | |------|--------------| | --output {table,json,yaml,csv} | Output format. Auto-flips to json when stdout is piped. | | --fields a,b,c | Project each row to those keys (drives column order in csv/table, projects objects in json/yaml). | | --web | Open the equivalent dashboard URL in a browser. Currently supported on event get, event stats, order get, addon list, brand info, and account verify; other commands accept the flag for forward-compatibility but no-op today (run <cmd> --help to confirm). | | --dry-run | Print the request that WOULD be sent and exit 0. Mutations only. | | --idempotency-key <uuid> | Forward as Idempotency-Key header. See Idempotency below. | | --non-interactive (-y) | Disable prompts; missing required input → exit 2. | | --no-color | Disable colored output (same as setting NO_COLOR=1). | | --upload field=path | On mutation commands: upload the local file via the presigned-S3 flow and substitute its CDN URL into the payload at field. Repeat for multiple assets. |

Run any command with --help for the full flag list. Did-you-mean suggestions fire on typos.

Idempotency

The CLI auto-generates a fresh UUID Idempotency-Key for every mutation by default. That protects in-process retries: if axios retries after a mid-flight network blip, it reuses the same key and the server replays its cached response — no double-create.

For cross-invocation safety — "if the user re-runs this exact command, it should be a no-op rather than a second create" — pass an explicit --idempotency-key <deterministic-uuid> derived from the operation (a stable id, a content hash, whatever). The server caches responses by key for 24h.

Full contract: docs/AGENT_GUIDE.md §7.

Upgrading

# npm
npm uninstall -g @theticketfairy/cli  # removes the pre-0.1.1 package if present
npm install -g ticketfairy@latest

# Homebrew
brew update && brew upgrade ticketfairy

# shell installer (idempotent — safe to re-run)
curl -fsSL https://cli.theticketfairy.com/install.sh | sh

Check what version you're on with ticketfairy --version. Release notes: github.com/theticketfairy/ticketfairy-cli/releases.

Troubleshooting

Your npm global bin isn't on PATH. Find it with $(npm prefix -g)/bin (the npm bin -g command was removed in npm 9) and add that directory to your shell's PATH. With nvm/fnm, switching Node versions changes the global bin path — re-install the CLI after switching, or use the shell installer instead (it installs to the version-independent ~/.ticketfairy/bin).

ticketfairy auth status              # who am I right now?
ticketfairy auth status --debug      # which source resolved the token?

• "No token found" → run ticketfairy login, or set TICKET_FAIRY_API_KEY.
• "Token expired" → for OAuth, run ticketfairy login again; for a PAT, mint or rotate one (ticketfairy auth tokens rotate <id>).
• "Invalid token" → most often this means you're pointed at the wrong environment. Check ticketfairy config list for api_base.

The OS keychain binding (@napi-rs/keyring) needs libsecret on Linux. On headless hosts where you can't install it, the CLI automatically falls back to ~/.config/ticketfairy/credentials (file mode 0600). Either install libsecret-1-dev (Debian/Ubuntu) / libsecret-devel (Fedora) to use the keychain, or accept the file fallback. In CI, prefer TICKET_FAIRY_API_KEY and skip credential storage entirely.

Pass --debug (or set DEBUG=ticketfairy / DEBUG=ticketfairy:*) to log every HTTP request, response status, and retry. TICKET_FAIRY_LOG_LEVEL={silent,error,warn,info,debug} sets the level exactly. Debug output goes to stderr, so stdout JSON stays clean for piping — and never includes your token.

ticketfairy event list --debug 2>requests.log

ticketfairy config get api_base                                  # current
ticketfairy config set api_base https://api.theticketfairy.com   # reset to production

TICKET_FAIRY_API_BASE in your environment overrides whatever's in the config file.

If none of the above helps, please open an issue with the output of ticketfairy --version and the failing command run with --debug.

Stability

This is v0.x. Until v1.0:

• The command surface, flag names, and JSON output schemas can change between minor releases.
• Breaking changes will be called out in release notes; we follow semver, and minor bumps may include breaking changes while we're pre-1.0.
• For CI and scripts, pin a specific version ([email protected]) so an upstream release can't silently break your pipeline.
• JSON output keys are the most stable surface — we prefer additive changes there and try to deprecate before removing.

The path to 1.0 is in docs/ROADMAP.md.

Support

• Bug reports / feature requests: github.com/theticketfairy/ticketfairy-cli/issues
• Security disclosures: [email protected] — please don't open a public issue for security-sensitive bugs.
• General product questions: your account manager, or [email protected].

Development

yarn install
yarn dev event list             # run from source
yarn build                      # compile to dist/
yarn test                       # vitest
yarn lint                       # eslint
yarn typecheck                  # tsc --noEmit

Architecture notes in docs/ARCHITECTURE.md. Contributing: CONTRIBUTING.md. PR review automation: docs/PR_REVIEW_AUTOMATION.md. Plugin authoring: docs/PLUGINS.md. Resource shapes: docs/SCHEMAS.md.

Command reference

The full per-command reference (flags, args, examples) lives in docs/commands/ — one page per topic, regenerated from the command sources by oclif readme on every release.

Command Topics

• ticketfairy account - Manage account-level state — verification (Stripe Identity), profile, etc.
• ticketfairy addon - Manage event add-ons (merch bundles, parking, VIP perks, …)
• ticketfairy api - Make a raw HTTP request against the Ticket Fairy API. Inherits auth, retry, idempotency-key, and JSON:API unwrap from the standard ApiClient.
• ticketfairy asset - Upload images and other files used by events, tickets, add-ons
• ticketfairy auth - Authenticate the CLI and manage credentials
• ticketfairy autocomplete - Display autocomplete installation instructions.
• ticketfairy brand - List your brands and choose the active one
• ticketfairy checkin - Inspect event check-in status
• ticketfairy config - Read, write, and clear CLI configuration values
• ticketfairy customer - View, search, and export customers
• ticketfairy event - Manage events
• ticketfairy help - Display help for ticketfairy.
• ticketfairy init - One-time setup wizard: log in, pick the active brand, set a default output format. Idempotent — safe to re-run.
• ticketfairy invitation - Send and manage event invitations
• ticketfairy manifest - Print the full command tree as structured JSON. Lets agents discover available commands, args, and flags programmatically — closing the gap that text-only --help leaves for non-human callers. Mirrors the static oclif.manifest.json shipped in the npm tarball, but includes plugin-loaded commands and works at dev time too.
• ticketfairy mcp - Boot a Model Context Protocol (MCP) server over stdio. Designed to be invoked by Claude Code (and other MCP-protocol clients) so they can drive Ticket Fairy through structured tool calls. Reuses the CLI's auth + ApiClient + retry + idempotency layer — no separate auth needed.
• ticketfairy messaging - List and send messaging campaigns
• ticketfairy order - View, refund, mark-paid, and export orders
• ticketfairy plugins - List installed plugins.
• ticketfairy promotion - Create and manage promo codes
• ticketfairy table - Manage table types (venue / club events with table service)
• ticketfairy team - Invite and manage team members
• ticketfairy ticket - Manage ticket types for an event
• ticketfairy tour - Manage tours — group multiple events into a single brandable run
• ticketfairy vault - Inspect the brand's Vault banking state (account, balance, cards, transactions, transfers, beneficiaries). Read-only. Vault is an invitation-only feature — commands will return a 403 / 404 from the backend for brands that haven't been onboarded.
• ticketfairy webhook - List, create, update, and delete webhooks (event / brand / tour scoped)

License

MIT — see LICENSE.