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.

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.