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 shared tasks, events and orders; 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.

Guest-list signup links

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 create club-night \
  --ticket-id 42 --enabled --approval-mode manual --max-companions 2 --capacity 50
usetix events guest-list forms club-night --json
usetix events guest-list form club-night --form-id FORM_ID --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 --form-id FORM_ID --enabled=false
usetix events guest-list rotate club-night FORM_ID --yes

Use create for another link with its own ticket and quota; new links are enabled by default. Pass --name Press for an internal label or --enabled=false to create a closed link. forms returns stable IDs; select one with --form-id for form, configure and optionally requests. rotate SLUG FORM_ID --yes invalidates only that public URL and returns its replacement; settings, requests and issued tickets remain valid. Without --form-id, legacy form/configure work only while an event has at most one link; multiple links return 409.

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.

Name and email are always asked. create and configure choose what else a link asks:

usetix events guest-list configure club-night --form-id FORM_ID \
  --phone required --companion-names optional --ask-checkout-questions
usetix events guest-list configure club-night --form-id FORM_ID \
  --company hidden --ask-checkout-questions=false

--company, --phone and --companion-names each take hidden, optional or required. New links ask for the company optionally and hide the others. Companions’ names are only asked while --max-companions is above 0. --ask-checkout-questions adds the event’s order-level checkout questions; --ask-checkout-questions=false stops asking them.

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

pending (the default) lists everything awaiting review: new signups and approved signups whose guest has since added companions. Each request shows the phone, companions’ names, answers and any pending addition. For a request with a pending addition, approve issues a separate party for the added companions and reject declines only them; the signup stays approved.

--count and --ids-only describe the current page; JSON also contains the pending_count for the selected link (or the whole event without a filter). 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.

Shared tasks

Available in CLI v0.7.0 and later. Existing Homebrew installations can update with brew update && brew upgrade gobijan/tap/usetix.

Use task public IDs from list and assignee membership IDs from people:

usetix tasks list --event october-party --assignee me --hide-done
usetix tasks people --event october-party
usetix tasks create --title "Confirm the door briefing" --event october-party --assignee 42 --due 2026-10-24
usetix tasks show TASK_ID
usetix tasks update TASK_ID --description "Meet at 18:00" --lock-version 0
usetix tasks move TASK_ID --status in_progress --before NEXT_TASK_ID --lock-version 1
usetix tasks comment TASK_ID --body "Entrance team confirmed."
usetix tasks comments TASK_ID
usetix tasks move TASK_ID --status done --lock-version 2
usetix tasks archive TASK_ID --lock-version 4
usetix tasks list --archived
usetix tasks restore TASK_ID --lock-version 5
usetix tasks delete TASK_ID --yes

Read each current lock_version with show before editing or moving; the values above are examples. Conflicts are reported without retrying the write. Optional fields can be cleared explicitly, for example --assignee= --due=. Description updates replace its complete rich text, including files. Omitted flags leave fields unchanged. --json, --ids-only and --count work on task lists, people and activity; JSON preserves rich HTML and attachment metadata.

Only completed tasks can be archived. Restore keeps them in Done. Deletion requires --yes and removes comments and history. Personal co-organizer tokens follow current event assignments; use an event when creating a task.

Private upload metadata and downloads use the direct API command:

usetix api POST /admin/task_uploads --data @upload-metadata.json
usetix api GET /admin/task_uploads/SIGNED_BLOB_ID --output briefing.pdf

Upload metadata contains a blob object with filename, content type, byte size and a base64 MD5 checksum. Transfer file bytes with PUT to the returned direct_upload.url, using its headers and an HTTP client. Do not send your Usetix Bearer token to storage. Embed the returned attachable_sgid in <action-text-attachment sgid="..."></action-text-attachment> HTML through tasks update --description or tasks comment --body.

See the Tasks API for the upload 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

Work with customers

List the people who bought from you with the dashboard’s filters, open one with their orders, and correct how they are addressed and reached:

usetix customers list --query acme --marketing-only
usetix customers list --event summer-festival --all --ids-only
usetix customers show 17
usetix customers update 17 --salutation ms --title Dr. --company "Acme GmbH"

--salutation takes ms, mr, mx, or none. Only the flags you pass change, and an empty value such as --phone "" clears a field. The email address stays as it is: it signs the customer in to your shop and ties their orders together. usetix customers contacts keeps the customer’s interaction timeline.

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:

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.

Lounge bookings

usetix events lounges list club-night
usetix events lounges bookings club-night --json
usetix events lounges accept club-night BOOKING_ID    # fee preview; no write
usetix events lounges accept club-night BOOKING_ID --yes
usetix events lounges reject club-night BOOKING_ID --yes
usetix events lounges cancel club-night BOOKING_ID --yes
usetix events lounges configure club-night --enabled --booking-mode request --yes

Acceptance charges the account’s fee plus VAT from Credit immediately. Cancellation and no-shows do not refund it. List output shows the current rate; JSON also preserves original booking charges. Lists support --count and --ids-only. Configuration changes only supplied flags. Use usetix api for venue catalog CRUD, event price overrides and photos. Lounge routes.