Usetix CLI

Die Usetix CLI ist der quelloffene Go-Client für Veranstalter, die schnell im Terminal arbeiten oder eine stabile Schnittstelle für Skripte und Coding-Agenten brauchen. Komfortable Befehle decken die häufigsten Event- und Bestellabläufe ab; mit usetix api erreichst Du jeden vorhandenen JSON-Endpunkt.

Quellcode und Releases findest Du unter github.com/gobijan/usetix-cli.

Installation

Mit Homebrew:

brew install gobijan/tap/usetix

Mit Go:

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

Fertige Binaries für macOS, Linux und Windows stehen im aktuellen GitHub-Release.

Prüfe die Installation:

usetix version

Anmelden

Erstelle in Usetix unter Einstellungen → API-Tokens einen Account-Token. Wähle Lesen für Reports und Abfragen oder Lesen + Schreiben nur dann, wenn die CLI Daten ändern soll.

Lass den Token anschließend von der CLI prüfen und speichern:

usetix auth login
usetix auth status

Die interaktive Eingabe blendet den Token aus und speichert ihn im System-Keyring. In CI oder einer anderen nicht interaktiven Umgebung kannst Du USETIX_TOKEN setzen:

export USETIX_TOKEN="dein-token"
usetix auth status

Tokens sind an einen Account gebunden. Du kannst sie jederzeit unter Einstellungen → API-Tokens widerrufen.

Mit Events arbeiten

Event-Befehle verwenden den Slug, der in URLs und in usetix events list angezeigt wird:

usetix events list
usetix events show summer-festival
usetix events update summer-festival --attendee-note "Bitte Ausweis zum Einlass mitbringen"
usetix events update summer-festival --listed=false
usetix events publish summer-festival
usetix events unpublish summer-festival

Lege einen Entwurf im Terminal an:

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

Mit --attendee-note setzt Du die Nachricht, die Ticketinhaber nach dem Kauf sehen; ein leerer Wert entfernt sie. usetix events create --help und usetix events update --help zeigen alle unterstützten Felder.

Gästelisten-Anmeldung per Link

Gäste nutzen ein kurzes Formular ohne Benutzerkonto. Wähle ein Standardticket für freie Platzwahl oder Stehplätze aus den ticket_options von usetix api GET /admin/events/club-night/guest_list und konfiguriere den 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

Mit create legst Du einen weiteren Link mit eigener Ticketart und eigenem Kontingent an. Neue Links sind standardmäßig aktiv. --name Presse setzt einen internen Namen, --enabled=false erstellt einen geschlossenen Link. forms liefert feste Kennungen; wähle eine mit --form-id bei form, configure und optional requests. rotate SLUG FORM_ID --yes macht nur diese öffentliche URL ungültig und liefert die neue zurück. Einstellungen, Anfragen und ausgestellte Tickets bleiben erhalten. Ohne --form-id funktionieren die bisherigen Befehle form/configure nur bei höchstens einem Link; mehrere Links liefern 409.

automatic verschickt QR-Tickets für neue gültige Anmeldungen sofort. Bei manual prüfst Du jede Anfrage zuerst. Die Freigabe prüft den Bestand und erstellt ein Ticket pro Person einschließlich Begleitung. Ablehnen verschickt keine E-Mail. Offene Anfragen reservieren keine Plätze. Der Wechsel zu automatic gibt ältere Anfragen nicht automatisch frei.

Nur übergebene Flags ändern Einstellungen. --enabled=false stoppt neue Anmeldungen und erhält vorhandene Anfragen und Tickets. --max-companions 0 erlaubt keine Begleitung. Bei mehreren Stehbereichen nutzt Du --standing-pool-id; 0 entfernt die Auswahl beim Wechsel zu freier Platzwahl. Event und Shop müssen veröffentlicht sein. Nummerierte Sitze bleiben in der manuellen Gästeliste.

Name und E-Mail werden immer abgefragt. Mit create und configure bestimmst Du, was ein Link zusätzlich abfragt:

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 und --companion-names nehmen jeweils hidden, optional oder required. Neue Links fragen die Firma optional ab und blenden den Rest aus. Namen der Begleitung werden nur abgefragt, solange --max-companions größer als 0 ist. --ask-checkout-questions fragt zusätzlich die Checkout-Fragen des Events pro Bestellung ab; --ask-checkout-questions=false schaltet das wieder aus.

Anfragen kommen absteigend nach Eingang, 25 pro Seite. Nutze --status pending, approved oder rejected und übergib die numerische next_page an --page, bis sie null ist:

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

pending (Standard) zeigt alles, was auf Freigabe wartet: neue Anmeldungen und freigegebene, bei denen der Gast inzwischen Begleitung nachgetragen hat. Jede Anfrage zeigt Telefon, Namen der Begleitung, Antworten und eine offene Nachmeldung. Bei einer offenen Nachmeldung stellt approve eine eigene Gruppe für die nachgetragene Begleitung aus, und reject lehnt nur diese ab; die Anmeldung bleibt freigegeben.

--count und --ids-only beziehen sich auf die aktuelle Seite; JSON enthält zusätzlich pending_count für alle wartenden Anfragen des gewählten Links oder, ohne Filter, des ganzen Events. Zur Bearbeitung brauchst Du die genaue public_id aus der Liste. Konfiguration und Freigabe/Ablehnung benötigen ein Schreib-Token. Co-Organisatoren können nur ihre aktuell freigegebenen Events bearbeiten. Siehe Gästeliste und API-Vertrag EN.

Mit Bestellungen arbeiten

Liste Bestellungen des aktuellen Monats, suche in Käufer- und Ticketdaten oder filtere auf ein Event:

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

Befehle für eine einzelne Bestellung akzeptieren beide Kennungen aus der Liste:

Bestellcode, zum Beispiel 8WZN-28GT: kurz und praktisch für Menschen. Formatierung sowie Groß- und Kleinschreibung spielen keine Rolle.
Public ID, zum Beispiel sm1KWiRAShvptqKrYzh6AKKJ: die stabile Kennung, die Integrationen speichern sollten.

usetix orders show 8WZN-28GT
usetix orders show sm1KWiRAShvptqKrYzh6AKKJ --json

Erstattungen, Stornierungen und das Archivieren brauchen eine ausdrückliche Bestätigung:

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

Mit Kunden arbeiten

Liste die Menschen, die bei Dir gekauft haben, mit den Filtern aus dem Dashboard, öffne einzelne mit ihren Bestellungen und korrigiere, wie Du sie ansprichst und erreichst:

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 nimmt ms (Frau), mr (Herr), mx (Divers) oder none. Nur die übergebenen Flags ändern sich, ein leerer Wert wie --phone "" leert ein Feld. Die E-Mail-Adresse bleibt, wie sie ist: Mit ihr meldet sich die Person in Deinem Shop an, und an ihr hängen ihre Bestellungen. usetix customers contacts führt den Verlauf der Interaktionen.

Pagination ohne Überraschungen

usetix orders list liefert die ersten 50 passenden Bestellungen. --limit akzeptiert Werte von 1 bis 100. Wenn eine weitere Seite vorhanden ist, zeigt die CLI einen opaken Cursor:

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

Versuche nicht, den Cursor zu lesen oder selbst zu bauen. Kopiere ihn exakt oder lass die CLI automatisch alle Seiten abrufen:

usetix orders list --period all --all

Der Unterschied ist wichtig: --all bedeutet alle Seiten innerhalb der gewählten Filter. Standardmäßig ist der Zeitraum der aktuelle Monat. Wenn Du wirklich die gesamte Bestellhistorie willst, brauchst Du deshalb --period all --all.

Wenn Du nur die Gesamtzahl brauchst, muss die CLI nicht jede Seite laden:

usetix --count orders list --period all

Mit Geschenkgutscheinen arbeiten

usetix vouchers list
usetix vouchers list --status blocked
usetix vouchers list --limit 25 --page NEXT_PAGE_CURSOR
usetix vouchers list --all
usetix vouchers show q7R9mT2vX4pL8nK6
usetix vouchers report

Listen zeigen maskierte Codes und verwenden Cursor-Pagination. Die exakte Suche sendet den vollständigen Code ausschließlich im Request-Body:

usetix vouchers list --query ABCD-2345-EFGH-6789

Manuell ausgestellte Gutscheine bekommen immer einen sicheren generierten Code:

usetix vouchers issue --amount 50.00 --note "Barverkauf"
usetix vouchers issue --product mN9uR4pKc8xQ

Bei der Ausgabe über ein Bonusprodukt bleibt dessen niedrigerer Kaufpreis als tatsächlich bezahlte Gegenleistung erhalten.

Feste Produkte können Bonusguthaben verkaufen:

usetix vouchers products create --name "Zahle 50, erhalte 75" \
  --amount 75.00 --purchase-price 50.00
usetix vouchers products create --name "Betrag wählen" --pricing flexible \
  --minimum 10.00 --maximum 250.00

Die Shop-Reihenfolge verwaltest Du per Drag-and-drop im Dashboard. Skripte können den Positions-Endpunkt über usetix api aufrufen. Guthabenänderungen, Sperren, Zustellungs-Retries und Imports verlangen die jeweiligen Bestätigungsflags; Details stehen im Gutschein-Guide.

Ausgabe für Menschen, Skripte und Agenten

Interaktive Terminals bekommen kompakte, formatierte Tabellen. Umgeleitete Ausgabe verwendet standardmäßig einen stabilen JSON-Umschlag. Wähle ein Format ausdrücklich, wenn ein anderes Programm das Ergebnis verarbeitet:

Flag	Ausgabe
`--json`, `-j`	Stabiler `{ "ok", "data", ... }`-Umschlag.
`--agent`	Deterministisches JSON für Coding-Agenten.
`--quiet`, `-q`	Reine JSON-Daten ohne Umschlag.
`--ids-only`	Eine Ressourcen-ID pro Zeile.
`--count`	Nur die Anzahl passender Ergebnisse.
`--styled`	Erzwingt die für Menschen lesbare Terminal-Ansicht.

Beispiele:

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

Zugriff auf die komplette API

Die komfortablen Befehle sind ein Einstieg, keine Grenze. Nutze usetix api METHOD PATH für jeden Endpunkt aus der Admin-API-Dokumentation EN:

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

JSON-Bodies können direkt im Befehl stehen, aus @datei kommen oder über stdin eingelesen werden. Downloads lassen sich in eine Datei oder nach stdout schreiben. Direkte DELETE-Requests benötigen --yes.

Profile und Completions

Profile halten Produktion, Staging und lokale Installationen getrennt:

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

Erzeuge Completion für Bash, Zsh, Fish oder PowerShell:

usetix completion zsh

Jeder Befehl hat kontextbezogene Hilfe. Starte mit usetix help, usetix orders --help oder usetix orders list --help.

Gemeinsame Aufgaben

Verfügbar ab CLI v0.7.0. Eine bestehende Homebrew-Installation aktualisierst Du mit brew update && brew upgrade gobijan/tap/usetix.

usetix tasks list --event oktoberparty --assignee me --hide-done
usetix tasks people --event oktoberparty
usetix tasks create --title "Einlassbriefing abstimmen" --event oktoberparty --assignee 42 --due 2026-10-24
usetix tasks show TASK_ID
usetix tasks update TASK_ID --description "Treffpunkt um 18 Uhr" --lock-version 0
usetix tasks move TASK_ID --status done --lock-version 1
usetix tasks comment TASK_ID --body "Team ist informiert."
usetix tasks comments TASK_ID
usetix tasks archive TASK_ID --lock-version 3
usetix tasks list --archived
usetix tasks restore TASK_ID --lock-version 4
usetix tasks delete TASK_ID --yes

IDs kommen aus list und people. Lies die aktuelle lock_version vor jeder Änderung mit show; die Zahlen oben sind Beispiele. Konflikte werden ohne automatischen Schreibversuch gemeldet. move --before NEXT_TASK_ID setzt eine Karte vor die angegebene Karte in der Zielspalte. Ohne --before kommt sie ans Ende. Leere optionale Flags wie --assignee= --due= entfernen diese Angaben. Nicht angegebene Felder bleiben unverändert.

Beschreibungen und Kommentare akzeptieren HTML. Eine Beschreibungsänderung ersetzt ihren gesamten Inhalt einschließlich Dateien. JSON-Ausgaben enthalten Rich Text und Dateimetadaten. --ids-only und --count funktionieren für Aufgabenlisten, Personen und den Verlauf.

Private Uploadmetadaten und Downloads sind über usetix api erreichbar. Die Dateibytes werden separat per HTTP-PUT an die signierte Speicher-URL übertragen, mit deren Headern und ohne den Usetix-Bearer-Token. Verwende danach die attachable_sgid im Action-Text-HTML.

Siehe Aufgaben und Tasks API (Englisch).

Promoter

Lade Promoter über die vorhandenen Team-Befehle ein und weise ihnen nach der Annahme Codes zu:

usetix team invite lisa@example.com --role promoter
usetix team list
# Nach Annahme der Einladung:
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

Neue Codes haben standardmäßig 0 % Rabatt. Ohne --event gilt ein Code shopweit; mit --discount-amount 10 vergibst Du einen Rabatt. Bestehende Codes verwaltest Du mit promo-codes list, show ID, update ID und reactivate ID --yes. update ID --promoter 0 entfernt eine unbenutzte Zuordnung. Nach einer Reservierung oder einem Verkauf ist die Zuordnung gesperrt.

promoters list zeigt Tickets und Umsatz nach Erstattungen je Promoter und Code. --period akzeptiert today, week, month, year oder all (Standard), jeweils in der Account-Zeitzone. Für Skripte gibt es --json. Diese Befehle benötigen einen Account-Token eines Inhabers oder Managers; Promoter nutzen ihr eigenes Web-Dashboard. Vollständige Promoter-Anleitung.

Einlass & Ankünfte

Die CLI liest den Bericht einmal pro Aufruf. --intervals ergänzt die lesbare Ausgabe um den Verlauf; --json enthält ihn immer. --count gibt die Zahl eingelöster Eintritte aus.

usetix events arrivals club-night --json

Zum Leitfaden für Einlass & Ankünfte.