English EN Deutsch DE Português PT Français FR Español ES
Start for Free

Usetix CLI

The Usetix CLI is the open-source Go client for organizers who want a fast terminal workflow or a stable interface for scripts and coding agents. Friendly commands cover common event and order work; usetix api reaches every existing JSON endpoint.

Source code and releases live at github.com/gobijan/usetix-cli.

Install

With Homebrew:

brew install gobijan/tap/usetix

With Go:

go install github.com/gobijan/usetix-cli/cmd/usetix@latest

Prebuilt binaries for macOS, Linux, and Windows are available from the latest GitHub release.

Confirm the installation:

usetix version

Sign in

Create an account token in Usetix under Settings → API Tokens. Choose Read for reporting and lookups, or Read + Write only when the CLI needs to change data.

Then let the CLI validate and store the token:

usetix auth login
usetix auth status

The interactive prompt hides the token and stores it in the system keyring. In CI or another non-interactive environment, provide USETIX_TOKEN:

export USETIX_TOKEN="your-token-here"
usetix auth status

Tokens are account-scoped. Revoke them at any time from Settings → API Tokens.

Work with events

Event commands use the event slug shown in URLs and in usetix events list:

usetix events list
usetix events show summer-festival
usetix events update summer-festival --attendee-note "Bring your ID to the entrance"
usetix events update summer-festival --listed=false
usetix events publish summer-festival
usetix events unpublish summer-festival

Create a draft from the terminal:

usetix events create \
  --title "Summer Festival" \
  --venue-id 7 \
  --starts-at 2026-09-12T18:00:00Z \
  --ends-at 2026-09-13T02:00:00Z \
  --sales-ends-at 2026-09-12T18:00:00Z

Use --attendee-note to set the message shown to ticket holders after purchase; pass an empty value to remove it. Run usetix events create --help or usetix events update --help for every supported field.

Guests use a short form without an account. Choose a standard GA or standing ticket using the ticket_options returned by usetix api GET /admin/events/club-night/guest_list, then configure the link:

usetix events guest-list configure club-night \
  --ticket-id 42 --enabled --approval-mode manual --max-companions 2 --capacity 50
usetix events guest-list form club-night --json
usetix events guest-list requests club-night
usetix events guest-list approve club-night REQUEST_ID --yes
usetix events guest-list reject club-night REQUEST_ID --yes
usetix events guest-list configure club-night --enabled=false

Use automatic to send QR tickets immediately for new valid signups, or manual to review each request first. Approval checks inventory and includes one ticket per companion. Rejection sends no email. Pending requests reserve no places, and changing to automatic mode does not approve older pending requests.

Only supplied flags change settings. --enabled=false stops new signups while preserving existing requests and tickets. --max-companions 0 allows no companions. For standing tickets with several pools, pass --standing-pool-id; use 0 to clear it when switching to GA. The event and shop must be published. Numbered seats remain in the manual guest-list workflow.

Requests are newest first, 25 per page. Use --status pending, approved or rejected and pass the numeric next_page to --page until it is null:

usetix events guest-list requests club-night --status approved --page 2 --json

--count and --ids-only describe the current page; JSON also contains the event-wide pending_count. Use the exact public_id from this list for review. Configuration and review require a write token. Co-organizer tokens follow current event assignments. See Guest list and the API contract.

Work with orders

List orders for the current month, search across buyer and ticket data, or filter to one event:

usetix orders list
usetix orders list --query susanna@example.com
usetix orders list --event summer-festival

Commands that operate on one order accept either identifier printed by the list:

  • Order code, for example 8WZN-28GT: short and convenient for people. Formatting and letter case are ignored.
  • Public ID, for example sm1KWiRAShvptqKrYzh6AKKJ: the stable identifier to store in integrations.
usetix orders show 8WZN-28GT
usetix orders show sm1KWiRAShvptqKrYzh6AKKJ --json

Refunds, cancellations, and archiving require explicit confirmation:

usetix orders refund 8WZN-28GT --amount 5.00 --yes
usetix orders cancel 8WZN-28GT --yes
usetix orders archive 8WZN-28GT --yes
usetix orders unarchive 8WZN-28GT

Share analytics reports

List active links or create a read-only report for a partner, sponsor, artist, venue, or client:

usetix analytics shares
usetix analytics share --event spring-showcase --period 30 --expires-in 7
usetix analytics share \
  --period custom \
  --start-on 2026-07-01 \
  --end-on 2026-07-31 \
  --branded=false

Periods are today, 7, 30, 90, or custom. Expiry is 7, 30, or 90 days. The report URL is a bearer secret; anyone with it can read the live values for the fixed date range until expiry or revocation.

Revoke by the numeric ID printed by analytics shares:

usetix analytics revoke 42 --yes

Use usetix analytics shares --ids-only, usetix analytics shares --count, or usetix analytics share ... --json in scripts. See Share analytics reports for the security model.

Work with gift vouchers

List balances and inspect the immutable ledger using the public voucher ID:

usetix vouchers list
usetix vouchers list --status blocked
usetix vouchers list --limit 25 --page NEXT_PAGE_CURSOR
usetix vouchers list --all
usetix vouchers list --query ABCD-2345-EFGH-6789
usetix vouchers report
usetix vouchers show q7R9mT2vX4pL8nK6

The report includes issued, redeemed, outstanding, currently paid shop-sales value, promotional bonus credit, and blocked counts. show also renders paid and bonus amounts plus buyer, recipient, and delivery support data when the voucher originated from a shop purchase. Voucher lists use opaque cursor pagination; --all follows every page automatically.

Issue a standalone voucher or use a configured fixed product:

usetix vouchers issue --amount 50.00 --note "Offline sale"
usetix vouchers issue --product mN9uR4pKc8xQ

Usetix generates a secure code for every manually issued voucher. Custom codes are supported only by the validated CSV import workflow. Issuing through a bonus product retains that product’s lower purchase price as paid consideration.

Financial and security changes require both a reason where applicable and explicit confirmation:

usetix vouchers adjust q7R9mT2vX4pL8nK6 \
  --direction debit --amount 5.00 --reason "Duplicate credit" --yes
usetix vouchers block q7R9mT2vX4pL8nK6 --reason "Compromised code" --yes
usetix vouchers unblock q7R9mT2vX4pL8nK6 --yes

Create fixed or flexible shop products:

usetix vouchers products list
usetix vouchers products show mN9uR4pKc8xQ
usetix vouchers products create --name "Gift 50" --pricing fixed --amount 50.00
usetix vouchers products create --name "Pay 50, get 75" --pricing fixed \
  --amount 75.00 --purchase-price 50.00
usetix vouchers products create --name "Choose amount" --pricing flexible \
  --minimum 10.00 --maximum 250.00 --visibility public_catalog
usetix vouchers products update mN9uR4pKc8xQ --status active --validity-months 36
usetix vouchers products remove-image mN9uR4pKc8xQ --yes
usetix vouchers products archive mN9uR4pKc8xQ --yes

Catalog order is managed by drag-and-drop in the dashboard. Scripts can use the documented product-position API through usetix api.

CSV imports are always previewed by the server. Omit --apply to inspect the structured validation result; issuing all clean rows requires both --apply and --yes:

usetix vouchers import vouchers.csv --json
usetix vouchers import vouchers.csv --apply --yes

Applying queues the atomic import and returns status applying; use usetix api get /admin/voucher_imports/IMPORT_ID to poll for applied or failed when a script must wait for completion.

See Gift vouchers for product and checkout behavior, and the Voucher API for every field and endpoint.

Pagination without surprises

usetix orders list returns the first 50 matching orders. --limit accepts 1 to 100. When another page exists, the CLI prints an opaque cursor:

usetix orders list --period all --limit 25
usetix orders list --period all --limit 25 --page NEXT_PAGE_CURSOR

Do not parse or construct the cursor. Copy it exactly, or let the CLI fetch every page:

usetix orders list --period all --all

The distinction matters: --all means all pages inside the selected filters. The default period is the current month, so use --period all --all when you really want the complete order history.

For only the total number of matching orders, fetching every page is unnecessary:

usetix --count orders list --period all

Output for humans, scripts, and agents

Interactive terminals get concise styled tables. Redirected output defaults to a stable JSON envelope. Select a mode explicitly when another program consumes the result:

Flag Output
--json, -j Stable { "ok", "data", ... } envelope.
--agent Deterministic JSON intended for coding agents.
--quiet, -q Raw JSON data without the envelope.
--ids-only One resource ID per line.
--count The matching result count only.
--styled Force the human-readable terminal view.

Examples:

usetix events list --json
usetix orders list --period all --ids-only
usetix --count orders list --event summer-festival

Reach the complete API

Typed commands are the convenient path, not a ceiling. Use usetix api METHOD PATH for any endpoint in the Admin API documentation:

usetix api GET /admin/customers
usetix api GET '/admin/analytics?period=month'
usetix api POST /admin/venues --data '{"name":"Hall 1","city":"Berlin"}'
usetix api PATCH /admin/events/summer-festival --data @event.json
usetix api GET /admin/orders.csv --output orders.csv

JSON request bodies can be inline, loaded from @file, or read from stdin. Downloads can be written to a file or to stdout. Direct DELETE requests require --yes.

Profiles and completions

Profiles keep production, staging, and local installations separate:

usetix profile create production --api-url https://app.usetix.io
usetix profile create local --api-url https://app.lvh.me
usetix profile use production
usetix --profile local auth login

Generate completion for Bash, Zsh, Fish, or PowerShell:

usetix completion zsh

Every command has contextual help. Start with usetix help, usetix orders --help, or usetix orders list --help.

Team and co-organizer access

usetix events invite-co-organizer friday-night promoter@example.com
usetix team list
usetix team access 42 --event friday-night --event saturday-night
usetix team deactivate 42 --yes
usetix events duplicate friday-night

team invite EMAIL --event SLUG accepts repeated --event flags. team access replaces the complete assignment; use --clear-events --yes to remove all assigned events. team reactivate, team invitations resend, and team invitations revoke --yes complete the existing team lifecycle.

Co-organizers create personal tokens through API Tokens in their sidebar and use the normal usetix auth login. Event commands and usetix api then follow their assigned events. Team commands remain with the venue. Personal tokens do not grant account settings, refund, customer-directory, or scanner access. Full team API contract.

Promoters

Invite promoters through the existing team commands, then assign codes after they accept:

usetix team invite lisa@example.com --role promoter
usetix team list
# After the invitation is accepted:
usetix promo-codes create --code LISA --promoter 42 --event summer-night
usetix promoters list --event summer-night --period month
usetix promo-codes deactivate 17 --yes

New codes default to 0% discount. Omit --event for a shop-wide code or add --discount-amount 10 for a discount. Use promo-codes list, show ID, update ID and reactivate ID --yes to manage existing codes. update ID --promoter 0 removes an unused assignment; assignments are locked after a reservation or sale.

promoters list reports tickets and revenue after refunds per promoter and code. Its optional --period accepts today, week, month, year or all (default), in the account timezone. Use --json for scripts. These commands require an owner or manager’s account token; promoters use their own web dashboard. Full promoter guide.

Admission & arrivals

The CLI reads the report once per command. --intervals adds the timeline to human-readable output; --json always includes it. --count prints checked-in admissions.

usetix events arrivals club-night --json

Read the admission and arrivals guide.