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 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
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.
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
--count und --ids-only beziehen sich auf die aktuelle Seite; JSON enthält zusätzlich pending_count für alle offenen Anfragen des 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
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.
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