pbx-Befehle

pbx ist ein Programm für macOS, Windows und Linux. Es ist gebaut und noch nicht veröffentlicht.

pbx [--hub NAME] [--agent INTEGRATION] [--output text|json] [--passphrase-file FILE] <command> [arguments]

--json ist dasselbe wie --output json. pbx help listet die Befehle; pbx host listet die, die mit host beginnen.

Konto

Befehl	Was er tut
pbx login	im Browser beim Portal anmelden; das Token kommt in den Schlüsselspeicher des Systems
pbx logout	das Token des Portals vergessen
pbx whoami	Konto, Team und Lizenz, mit denen dieser Rechner angemeldet ist
pbx licence	die Lizenz, wie Hub und Portal sie sehen

Der Hub

Befehl	Was er tut
pbx up NAME [--location nbg1] [--server-type cpx02] [--plan] [--yes] [--abort]	einen Hub in deinem Hetzner-Projekt anlegen, diesen Rechner als Owner koppeln, die Lizenz aktivieren
pbx status [NAME]	der Hub: seine Lizenz, Server, Twins, offene Freigaben und Releases, die Verbindung jedes Hubs auf diesem Rechner, und das Alpha-Label
pbx open [PATH]	das Portal des Hubs im Browser, über einen lokalen Proxy, solange pbx läuft
pbx upgrade [NAME] --dist DIR [--plan] [--allow-from ADDR]	ein anderes Release von pbx-hub auf dem Server des Hubs installieren; Daten und Kopplungen bleiben
pbx down NAME [--plan] [--confirm NAME] [--keep-image]	den Hub löschen und was pbx up angelegt hat

Hetzner-Tokens: --token-file F oder --hcloud-context C für Production, --twins-token-file F oder --twins-hcloud-context C für Twins; sonst HCLOUD_TOKEN, sonst eine Eingabeaufforderung.

Hubs

Ein Rechner kann mit mehreren Hubs gekoppelt sein, mit einem eigenen Gerät für jeden. Ein Befehl spricht mit einem davon, gewählt in dieser Reihenfolge: --hub NAME (oder pbx status NAME), dann PBX_HUB, dann der Standard-Hub, dann der einzige Hub, den es gibt. Bei mehreren Hubs ohne Standard verlangt der Befehl --hub.

Befehl	Was er tut
pbx hub list	die Hubs auf diesem Rechner: Endpunkt, Gerät, Schutzstufe, der Standard (*), und ob ein pbx open eine Verbindung hält
pbx hub current	der Hub, mit dem ein Befehl jetzt spricht, und warum (--hub, PBX_HUB, der Standard, der einzige)
pbx hub use NAME	NAME zum Standard-Hub machen; --hub und PBX_HUB gehen weiter vor

pbx hub list und pbx hub current sprechen mit keinem Hub; sie lesen die Dateien dieses Rechners. Die erste Kopplung setzt den Standard, wenn es keinen gibt; pbx down des Standard-Hubs löscht ihn.

Jeder Befehl, der an einem Hub etwas ändert, gibt zuerst hub: NAME auf stderr aus. Mit --output json gibt es diese Zeile nicht; das JSON hat stattdessen ein Feld hub. Befehle, die nur lesen, geben keins von beiden aus.

Geräte

Befehl	Was er tut
pbx pair --listener URL --code CODE	diesen Rechner über den Kopplungs-Listener des Hubs koppeln
pbx pair invite --role ROLE [--name NAME]	eine Einladung für ein anderes Gerät (Owner): eine Zeichenkette, 10 Minuten gültig
pbx pair INVITE	diesen Rechner mit einer Einladung koppeln
pbx devices	die Geräte des Hubs
pbx devices revoke ID|NAME [--confirm NAME]	ein Gerät widerrufen (Owner)

Coding-Agenten

Befehl	Was er tut
pbx --agent INTEGRATION <command>	einen Befehl als Coding-Agent ausführen (claude-code, cursor, …), signiert mit dem Agentenschlüssel dieses Geräts für diese Integration
pbx agent register INTEGRATION	den Agentenschlüssel dieses Geräts für eine Integration beim Hub registrieren (eine Person, einmal; pbx --agent tut es bei der ersten Nutzung)
pbx agent revoke INTEGRATION [--device ID]	den Agentenschlüssel eines Geräts für eine Integration widerrufen (den dieses Geräts, oder als Owner jeden)

Im Agentenmodus hält der Hub jede Anfrage unter der Obergrenze des Agenten. Darüber endet der Befehl mit 4; was eine Person freigeben muss, endet mit 5 und der ID der Freigabe. Ist PBX_AGENT gesetzt, werden pbx open, pbx approve, das Koppeln und pbx agent register|revoke abgelehnt (Exit 4); pbx weicht nie auf den Schlüssel der Person aus. Die Einzelheiten stehen unter Coding-Agenten.

Hosts und Releases

Befehl	Was er tut
pbx host create NAME [--type cpx22] [--env production|staging] [--location L] [--release V]	ein Production- oder Staging-Host mit Podman
pbx host list	die Production- und Staging-Hosts
pbx host delete NAME [--confirm NAME]	einen Host und seinen Server löschen (ein Gerät unter presence fragt eine Freigabe an)
pbx open host NAME [--ttl 1h] [--no-browser]	die nicht öffentliche Seite eines Staging-Hosts im Browser, wie pbx open twin
pbx host access NAME [--from ADDR,…] [--ttl 1h]	ein Web-Zugangslink zu einem nicht öffentlichen Staging-Host
pbx host access list NAME [--all]	die Web-Zugänge eines Staging-Hosts
pbx host access revoke NAME GRANT	einen Web-Zugang eines Staging-Hosts widerrufen
pbx host public NAME [on|off] [--confirm NAME]	ob ein Staging-Host öffentlich ist (80/443 von überall, mit eigenem TLS); on verlangt den eingetippten Namen
pbx host reseed NAME [--copy-from PRODUCTION] [--confirm NAME]	die Daten eines Staging-Hosts neu befüllen, aus dem Seed oder mit einer Kopie von Production
pbx release list	die Releases, die der Hub importiert hat
pbx release promote VERSION --host NAME [--now]	einen Host auf ein Release bringen

Twins

Befehl	Was er tut
pbx twin create --production HOST --task TASK [--branch B] [--ttl H] [--data seed|copy|empty]	ein Twin eines Production- oder Staging-Hosts; seine Daten aus dem Seed (Standard), leer oder bewusst eine Kopie von Production
pbx twin list [--all]	die Twins, mit ihren Daten und Web-Zugängen
pbx twin show TWIN	ein Twin: sein Zustand, seine Daten (Seed, Maskierung, ihre Logs) und sein Web-Zugang
pbx twin extend TWIN --hours H	einen Twin einmal verlängern
pbx twin reset TWIN	die Daten eines Twins auf seinen Checkpoint zurücksetzen
pbx twin reseed TWIN	den Seed eines Twins neu laufen lassen: sein Volume geleert, der Seed seiner Revision ausgeführt, ein neuer Checkpoint
pbx twin delete TWIN [--confirm TASK]	einen Twin und seinen Server löschen
pbx twin evidence TWIN	was der Hub über einen Twin weiß, mit Digest
pbx twin settings [--type T --location L]	das Hetzner-Projekt der Twins (Owner)
pbx open twin TWIN [--ttl 1h] [--no-browser]	die Seite eines Twins im Browser: ein Zugang für die Adresse dieses Geräts; ohne DNS-Zone ein lokaler Proxy, solange pbx läuft
pbx twin access TWIN [--from ADDR,… | --any] [--ttl 1h]	ein Web-Zugangslink für genannte Adressen (--any: ein presence-Gerät, ein Seed-Twin, höchstens 8 Stunden)
pbx twin access list TWIN [--all]	die Web-Zugänge eines Twins
pbx twin access revoke TWIN GRANT	einen Web-Zugang eines Twins widerrufen

Kopien der Produktionsdaten und DNS

Befehl	Was er tut
pbx env copy PRODUCTION	ob Twins eine Kopie der Daten eines Production-Hosts halten dürfen, maskiert oder nicht, und wer es festgelegt hat
pbx env copy allow PRODUCTION --reason R [--mask required|waived] [--confirm NAME]	Kopien der Produktionsdaten in Twins erlauben (Owner, presence-Gerät; die Warnung des Hubs wird gezeigt, der Name eingetippt)
pbx env copy forbid PRODUCTION [--confirm NAME]	Kopien wieder verbieten (Owner)
pbx dns status	DNS-Zone, Basisname, Wildcard-Eintrag und Zertifikat der Twins (Owner)
pbx dns setup --zone ZONE [--base NAME] [--email E] [--accept-terms] [--caa]	Twins als <task>.<base> aus einer Zone in Hetzners Cloud DNS benennen (Owner); das Token aus --dns-token-file F oder --dns-hcloud-context C
pbx dns verify	Zone und Wildcard-Eintrag erneut prüfen (Owner)

Freigaben und Skripte

Befehl	Was er tut
pbx approvals [--all]	was Agenten und begrenzte Geräte zur Freigabe durch eine Person angefragt haben
pbx approve ID [--confirm NAME]	eine freigeben, signiert mit dem Schlüssel dieses Geräts (nur presence)
pbx reject ID	eine ablehnen
pbx api METHOD PATH [JSON|-]	eine signierte Anfrage an die API des Hubs
pbx version	die Version

Eine Verbindung pro Gerät

Ein lang laufendes pbx (pbx open, pbx open twin, pbx open host) teilt seinen Tunnel zum Hub, solange es läuft, mit den anderen pbx-Läufen desselben Benutzers, Hubs und Geräts, über einen Socket, den nur dieser Benutzer öffnen kann. Jeder Lauf spricht weiter selbst TLS mit dem Hub und signiert seine Anfragen selbst; geteilt wird nur der Transport. Ohne ein lang laufendes pbx öffnet jeder Lauf seinen eigenen Tunnel. pbx status und pbx hub list zeigen die Verbindung: open via pbx open (pid …) mit dem Alter des letzten Handshakes, oder none. Unter Windows wird keine Verbindung geteilt: Dort läuft ein lang laufendes pbx pro Gerät.

Umgebung

Variable	Was sie tut
PBX_HUB	der Hub, mit dem ein Befehl spricht, vor dem Standard; --hub geht vor
PBX_AGENT	Agentenmodus für jeden Lauf, wie --agent; in der Umgebung des Agenten setzen
PBX_AGENT_SESSION	die Sitzung des Agenten im Audit; Standard: eine pro pbx-Lauf
PBX_LINK_SHARE	off: für diesen Lauf keine geteilte Verbindung nutzen oder anbieten
PBX_HOME	ein Verzeichnis für alle Dateien von pbx
PBX_PASSPHRASE_FILE, PBX_PASSPHRASE	die Passphrase der Schlüsseldatei des Geräts, wie --passphrase-file (Stufe passphrase-stored)
PBX_CLEVIS_CONFIG, PBX_CLEVIS_PIN	der Tang-Server (und sss mit dem TPM) für eine von Tang entsperrte Schlüsseldatei (Stufe tang)
PBX_NO_BROWSER	gesetzt: Links ausgeben statt einen Browser zu öffnen
HCLOUD_TOKEN, HCLOUD_CONFIG	das Hetzner-Token, oder die Konfiguration des hcloud-CLI für --hcloud-context
PBX_PORTAL, PBX_RELEASES	ein anderes Portal oder ein anderer Release-Server, für ein Labor

Ohne PBX_HOME liegen die Dateien unter macOS in ~/Library/Application Support/pbx, unter Windows in %LOCALAPPDATA%\pbx und unter Linux in den XDG-Verzeichnissen.

Exit-Codes

Code	Bedeutung
0	ok
1	fehlgeschlagen
2	falscher Aufruf
3	der Hub hat mit einem Status außer 2xx geantwortet
4	von einer Regel abgelehnt: einer Obergrenze, der Schutzstufe, oder ein Befehl einer Person mit gesetztem PBX_AGENT
5	wartet auf die Freigabe einer Person; die ID der Freigabe wird ausgegeben (mit --output json die Freigabe auf stdout)