nyx-CLI-Referenz

nyx ist der Kommandozeilen-Client für nyxory. Damit verwalten Sie Projekte und Apps aus Ihrem Terminal. Viele derselben Operationen stehen auch einem Coding-Agenten wie Claude Code, Cursor oder Codex als nyx_*-MCP-Tools zur Verfügung, mit denen er in Ihrem Auftrag ausrollt (siehe MCP-Tools). Jeder Befehl unterstützt --json für Skripte und CI.

Globale Flags

Diese gelten für jeden Befehl.

Flag	Beschreibung
--json	Gibt pro Aufruf ein JSON-Objekt mit festem Aufbau aus (bei Erfolg auf stdout, bei einem Fehler auf stderr).
--context <name>	Überschreibt den aktiven Kontext für diesen Aufruf. Lässt sich auch über die Umgebungsvariable NYX_CONTEXT setzen.
--version	Gibt die Version der CLI aus.

Die Umgebungsvariable NYX_TOKEN liefert ein Bearer-Token anstelle des Schlüsselbunds des Betriebssystems. Das ist nützlich für CI.

Hinweis: Wo ein Befehl ein Argument <project> nimmt, akzeptiert er drei Formen: den vollständigen Namespace (nyx-abc123), die reine ID (abc123) oder die lesbare Anzeigebezeichnung. Eine mehrdeutige Bezeichnung liefert den Fehler project_ambiguous.

nyx login

nyx login [--api <url>] [--console <url>] [--hostname <name>] [--context <name>]

Meldet Sie über einen Browser per OAuth-2.0-Loopback-Redirect (RFC 8252) an und speichert ein langlebiges API-Token im Schlüsselbund des Betriebssystems (Keychain unter macOS, libsecret unter Linux, Wincred unter Windows), abgelegt pro Kontext. Bei Erfolg wird der Zielkontext aktiv.

• --api <url>: Basis-URL der API. Standard ist die gespeicherte URL des Zielkontexts oder die Produktions-API.
• --console <url>: Basis-URL der Console. Gleiche Standardregel wie bei --api.
• --hostname <name>: Name, unter dem das Token gespeichert wird. Standard ist der Hostname des Rechners.
• --context <name>: Kontext, in dem Sie sich anmelden und der aktiv wird. Standard ist der aktuell aktive Kontext oder prod bei einer frischen Installation.

Frische Installationen bringen die Kontexte prod und dev schon mit. nyx login und nyx login --context dev brauchen deshalb kein --api/--console.

Hinweis: nyx login öffnet einen Browser und wartet bis zu 5 Minuten auf den Callback. Der Befehl ist nicht headless-tauglich. Für CI oder einen Rechner ohne Oberfläche setzen Sie stattdessen die Umgebungsvariable NYX_TOKEN (umgeht die Anmeldung vollständig) oder erzeugen auf einem angemeldeten Rechner ein Token mit nyx token create und geben es über NYX_TOKEN weiter.

nyx setup

nyx setup [--all] [--client <list>] [--skip-login] [--no-auto-approve]

Verbindet jeden MCP-fähigen KI-Client auf dem Rechner (Claude Code, Cursor, Codex, VS Code, Claude Desktop) in einem Durchgang mit dem MCP-Endpunkt von nyxory (<api_url>/mcp) und meldet Sie vorher an, falls kein Token gespeichert ist. Jeder Client verbindet sich direkt über HTTP und führt sein eigenes OAuth durch. Die CLI erzeugt nie ein Token und bettet keines ein.

• --all: Verbindet jeden erkannten Client ohne Rückfrage.
• --client <a,b,...>: Verbindet nur die aufgeführten Clients (claude, cursor, codex, vscode, claude-desktop), auch wenn sie nicht erkannt wurden.
• --skip-login: Bricht mit einem Fehler ab, statt die Anmeldung im Browser zu starten, wenn kein Token gespeichert ist.
• --no-auto-approve: Gibt Aufrufe von nyxory-Tools in den verbundenen Clients nicht vorab frei.

Standardmäßig interaktiv. Der Befehl zeigt eine Checkliste der erkannten Clients zur Auswahl und fragt bei Claude Code gezielt, ob die Web- oder die lokale Installation verwendet werden soll. Übergeben Sie --all (oder --client ...) zusammen mit --json oder in einer Shell ohne TTY, um jede Rückfrage zu überspringen. Ohne --all endet der Befehl in diesem Modus mit dem Fehler confirmation_required. Claude Desktop braucht immer einen manuellen Schritt. nyx setup gibt die Connectors-URL aus, die Sie in claude.ai einfügen, weil es keine lokale Konfigurationsdatei zu schreiben gibt.

Wiederholtes Ausführen ist idempotent. Die nyxory-Registrierung wird an Ort und Stelle überschrieben, jeder andere bereits in einem Client konfigurierte MCP-Server bleibt erhalten.

nyx account

nyx account <subcommand>

Abonnement und Ressourcen-Kontingent auf Kontoebene. Derzeit gibt es einen Unterbefehl.

nyx account ram

nyx account ram

Zeigt das RAM-Kontingent des gesamten Kontos: Grundkontingent des Tarifs, zusätzliche Pakete und wie viel bereits über alle Projekte zugeteilt ist. Führen Sie den Befehl aus, bevor Sie entscheiden, ob sich die Zuteilung eines Projekts (nyx project ram) erhöhen lässt. Keine Flags außer den globalen.

Ausgabe: Tarif und Tarif-ID, Status, Grundkontingent an RAM (oder „unlimited“ bei Enterprise), RAM-Pakete (je 1 GB), Gesamtkontingent des Kontos, Speichergrenze, Add-ons und eine Upgrade-URL, wenn eine zutrifft.

nyx app

nyx app <subcommand>

Reine Leseansicht ausgerollter Apps. Jeder Unterbefehl hier liest nur den Zustand. Apps legt Ihr Coding-Agent an, indem er das MCP-Tool nyx_brain aufruft, nicht diese CLI.

nyx app list

nyx app list (Alias: nyx app ls)

Listet Apps (App Custom Resources, keine rohen Kubernetes-Deployments) über alle Projekte, die Ihnen gehören. Keine Flags außer den globalen.

nyx app list --json | jq '.data.items[] | select(.phase != "Available")'

nyx app get

nyx app get <project> <name>

Zeigt die Details einer App: Phase, Anzahl der Replikate, Image, öffentliche Ingress-Domains. Beide Argumente sind Pflicht.

nyx app deployments

nyx app deployments <project> <name> (Alias: nyx app rollouts)

Zeigt die Rollout-Historie, eine Zeile pro ReplicaSet bzw. Revision.

nyx app logs

nyx app logs <project> <name> [--tail <n>] [--since <duration>] [--container <name>] [--pod <name>] [--grep <text>] [--previous]

Liest die Container-Logs einer App direkt, ohne Umweg über kubectl. Die Zeilen tragen RFC3339-Zeitstempel. Läuft kein Pod, erscheint eine klare Meldung.

Flag	Standard	Beschreibung
--tail	200	Maximale Anzahl Zeilen
--since	—	Nur Zeilen, die neuer sind als diese relative Dauer (z. B. 15m, 1h)
--container	erster Container des Pods	Welcher Container gelesen wird
--pod	neuestes Replikat	Welcher Pod gelesen wird
--grep	—	Filter auf einen Teilstring, Groß- und Kleinschreibung wird unterschieden
--previous	false	Liest die Logs des vorherigen, abgestürzten Containers

nyx app verify

nyx app verify <project> <name> [--timeout <seconds>]

Prüft die öffentlichen Ingress-Domains einer App mit einem HTTP-GET und meldet Status und Latenz pro Host. Eine Prüfung gilt unter Status 500 als „ok“. Ist eine Prüfung nicht in Ordnung, endet der Befehl mit einem Exit-Code ungleich null. So lässt er sich in CI verketten:

nyx app verify foo bar && deploy-prod

• --timeout <seconds>: HTTP-Timeout pro Prüfung. Standard 10.

nyx brain

nyx brain <repo-url> [--project <project>] [--agent-briefing <text>]

Versteckter Befehl, er erscheint nicht in nyx --help. Er ist das CLI-Gegenstück zum MCP-Tool nyx_brain, das Ihr Coding-Agent aufruft, um ein Deploy-Cookbook zu holen. Ein POST an /api/brain/deploy liefert eine Anleitung in Markdown plus einen Scan des Repos und den aktuellen Zustand des Zielprojekts. Der Agent liest das Cookbook und steuert die nyx_*-Grundbausteine selbst. Es gibt keinen Planer im Pod und kein Streaming.

Hinweis: Menschen tippen diesen Befehl normalerweise nicht selbst. Er dient dem lokalen Debugging dessen, was der Agent sieht.

• --project <project>: Projekt, für das das Cookbook geholt wird. Fällt auf die .nyxrc zurück, die beim Aufsteigen vom aktuellen Verzeichnis gefunden wird. Bleibt das Feld leer und lässt sich nichts auflösen, liefert der Server ein allgemeines Cookbook.
• --agent-briefing <text>: Freie Angaben zum Hintergrund (Stack, Komponenten, Deploy-Absicht, Umgebungsvariablen). Übergeben Sie -, um das Briefing von stdin zu lesen.

.nyxrc: Legen Sie eine TOML-Datei mit project = "widget" ins Wurzelverzeichnis eines Repos, um das Standard---project festzulegen. Eine .nyxrc pro App in einem Monorepo hat Vorrang vor der übergeordneten.

nyx context

nyx context <subcommand>

Legt fest, mit welchem nyxory-Stack (prod, dev, local-stack oder ein eigener) die CLI spricht. Ein Kontext bündelt eine API-URL, eine Console-URL, eine Identität und ein Bearer-Token. Frische Installationen bringen prod (aktiv) und dev schon mit.

nyx context list

nyx context list

Listet jeden konfigurierten Kontext. Der aktive ist mit * markiert. Keine Flags außer den globalen.

nyx context use

nyx context use <name>

Setzt <name> als aktiven Kontext und speichert das in config.toml. Meldet context_not_found, wenn der Name nicht konfiguriert ist.

nyx context show

nyx context show

Gibt den aufgelösten aktiven Kontext aus: Name, API-URL, E-Mail-Adresse und ID des Nutzers, Hostname und ob ein Token vorhanden ist. Die schnelle Antwort auf die Frage „Auf welchem Stack bin ich?“

nyx context remove

nyx context remove <name> (Alias: nyx context rm)

Löscht den genannten Kontext aus der Konfiguration und seinen Token-Eintrag im Schlüsselbund. Idempotent, ein fehlender Eintrag im Schlüsselbund ist kein Fehler. War der entfernte Kontext aktiv, wird wieder prod aktiv.

Hinweis: Anders als project delete, domain remove und token delete hat dieser Befehl kein Flag --yes und fragt nie nach. Er löscht sofort.

nyx claude

nyx claude <install|uninstall>

Verbindet Claude Code mit dem nyxory-MCP oder trennt die Verbindung, über claude mcp add --transport http. Das ist ein direkter Remote-Endpunkt. Claude Code führt sein eigenes OAuth durch, es wird kein Token eingebettet.

nyx claude install

nyx claude install [--scope user|local] [--no-auto-approve]

• --scope: user (alle Projekte) oder local (nur dieses Projekt). Standard user.
• --no-auto-approve: Gibt Aufrufe von nyxory-Tools nicht vorab frei.

Erfordert die claude CLI im PATH (sonst Fehler claude_install_failed). Entfernt außerdem Altlasten älterer nyx-Versionen: die alte Subagent-Datei @nyxory und einen alten Hook-Eintrag SessionStart. Beide sind durch die Init-Anweisungen des MCP-Servers ersetzt. Die Vorab-Freigabe schreibt eine Wildcard-Erlaubnisregel in die settings.json von Claude Code. Destruktive Tools bleiben unabhängig davon auf dem Server an eine Freigabe gebunden.

nyx claude uninstall

nyx claude uninstall [--scope user|local]

• --scope: Standard user.

Führt claude mcp remove <name> --scope <scope> aus, entfernt die Berechtigungsregeln und löscht die alte Subagent-Datei sowie (nur im Scope user) den alten Hook. „Not registered“ gilt als sauberes Ergebnis, nicht als Fehler.

nyx codex

nyx codex <install|uninstall>

Verbindet Codex CLI mit dem nyxory-MCP oder trennt die Verbindung, indem es die Tabelle [mcp_servers.nyxory] in ~/.codex/config.toml direkt bearbeitet. Andere Server, Einstellungen und Kommentare bleiben erhalten.

nyx codex install

nyx codex install [--no-auto-approve]

• --no-auto-approve: Gibt Aufrufe von nyxory-Tools nicht vorab frei.

Auf einem TTY startet der Befehl sofort das Browser-OAuth von Codex (codex mcp login), da Codex nicht von selbst danach fragt. Ohne TTY gibt er stattdessen die manuelle Anweisung codex mcp login nyxory aus.

nyx codex uninstall

nyx codex uninstall

Keine Flags außer den globalen. Meldet, ob ein Eintrag entfernt wurde.

nyx cursor

nyx cursor <install|uninstall>

Verbindet Cursor mit dem nyxory-MCP oder trennt die Verbindung, indem es ~/.cursor/mcp.json (oder ./.cursor/mcp.json mit --scope local) direkt bearbeitet. Einen CLI-Befehl cursor mcp add, an den es übergeben könnte, gibt es nicht.

nyx cursor install

nyx cursor install [--scope user|local] [--no-auto-approve]

• --scope: user (~/.cursor/mcp.json, alle Projekte) oder local (./.cursor/mcp.json). Standard user.
• --no-auto-approve: Gibt Aufrufe von nyxory-Tools nicht vorab frei.

Holt nach Möglichkeit den Katalog der MCP-Tools, um die Liste autoApprove von Cursor zu füllen.

nyx cursor uninstall

nyx cursor uninstall [--scope user|local]

• --scope: Standard user.

nyx vscode

nyx vscode <install|uninstall>

Verbindet VS Code (Agent-Modus von GitHub Copilot) mit dem nyxory-MCP oder trennt die Verbindung, indem es die mcp.json des Nutzerprofils direkt schreibt.

nyx vscode install

nyx vscode install

Keine befehlsspezifischen Flags. VS Code hat noch keinen Freigabe-Mechanismus pro Server, deshalb gibt es bei diesem Befehl kein --no-auto-approve.

nyx vscode uninstall

nyx vscode uninstall

Keine befehlsspezifischen Flags.

nyx domain

nyx domain <add|list|status|remove>

Verwaltet eigene Hostnamen für Apps (HTTPS über cert-manager und Traefik). Eine Domain durchläuft RoutingPending → CertPending → Ready. In der Ausgabe mit --json sagt next.action, auf welchen Zustand Sie warten (wait_routing, wait_cert, ready oder failed).

nyx domain add

nyx domain add <hostname> --app <name> [--project <project>] [--service-name <name>] [--service-port <port>] [--path-prefix <path>]

Registriert einen eigenen Hostnamen für eine App. Die Antwort enthält den CNAME (und gegebenenfalls einen A-Record für die Apex-Domain), auf den Sie DNS zeigen lassen. <hostname> muss eine echte Subdomain nach RFC 1123 sein, ohne Wildcards.

Flag	Pflicht	Beschreibung
--app <name>	ja	App, an die der Hostname geleitet wird
--project <project>	nein	Projekt, dem die App gehört. Nötig, wenn der App-Name über mehrere Projekte hinweg mehrdeutig ist
--service-name <name>	nein	Legt fest, auf welchen Service der Ingress zeigt (Standard: der einzige Service der App oder der mit dem Label nyxory.com/primary-service)
--service-port <port>	nein	Legt den Port des Service fest (Standard: der erste Port des Service)
--path-prefix <path>	nein	Pfadpräfix des Ingress. Standard /

nyx domain list

nyx domain list [--project <project>] [--app <name>] (Alias: nyx domain ls)

Listet eigene und automatisch erzeugte Domains. Ohne Filter erscheinen die Domains aller Projekte, die das Token sehen kann, in einer gemeinsamen Liste.

nyx domain status

nyx domain status <hostname> [--watch] [--timeout <duration>]

Zeigt Phase, Bedingungen, DNS-Ziel und den Hinweis auf die nächste Aktion für eine Domain.

• --watch: Fragt alle 5 Sekunden ab und endet, sobald die Domain Ready erreicht (oder bei Timeout bzw. Fehler).
• --timeout <duration>: Frist für --watch (z. B. 5m, 30s). Standard 10m. Ohne --watch wird der Wert ignoriert.

--watch blockiert mit einem Spinner, ist aber headless-tauglich. Es beachtet --json und öffnet nie eine Rückfrage im TTY. Eine verpasste Frist endet mit einem Exit-Code ungleich null und dem Fehlercode timeout.

nyx domain remove

nyx domain remove <hostname> [--yes|-y] (Aliasse: rm, delete)

Löscht eine Domain. Ingress, Certificate und TLS-Secret werden über den Finalizer des Operators sofort mitgelöscht.

• --yes / -y: Überspringt die Bestätigung.

Ohne --yes auf einem TTY fragt der Befehl nach einem getippten yes. In einer Shell ohne TTY oder mit --json und ohne --yes endet der Befehl mit einem Exit-Code ungleich null und confirmation_required, statt fortzufahren oder stillschweigend zu überspringen.

nyx project

nyx project <list|add|rename|delete|state|ram>

Verwaltet Projekte, also die Kubernetes-Namespaces, in die Apps ausgerollt werden.

nyx project list

nyx project list (Alias: nyx project ls)

Listet jedes Projekt. Keine Flags außer den globalen.

nyx project add

nyx project add <name> [--label "..."] [--no-wait]

Legt ein neues Projekt an. <name> wird zur Anzeigebezeichnung, sofern --label sie nicht überschreibt. Der Server vergibt einen stabilen Namespace nyx-<id>. Das ist die ID, die jeder andere Befehl erwartet.

• --label <text>: Freier Anzeigename. Standard ist das Argument <name>.
• --no-wait: Kehrt sofort zurück, statt (bis zu 60 Sekunden) abzufragen, bis das Projekt phase=Ready erreicht.

Standardmäßig fragt der Befehl mit einem Spinner im Terminal ab. Für Skripte nutzen Sie --no-wait oder --json. --json kehrt sofort mit dem Hinweis next: poll_project zurück.

nyx project rename

nyx project rename <id> <label>

Ändert die Anzeigebezeichnung eines Projekts. Die ID (der Namespace) selbst ist unveränderlich. Keine Flags außer den globalen.

nyx project delete

nyx project delete <id> [--yes|-y] (Aliasse: rm, remove)

Destruktiv. Löscht jeden Workload, jedes Secret, jeden Ingress und jede ConfigMap im Projekt. Nicht wiederherstellbar.

• --yes / -y: Überspringt die Bestätigung.

Gleiche Bestätigungsregel wie bei domain remove. Ein TTY ohne --yes fragt nach einem getippten yes. Eine Shell ohne TTY oder --json ohne --yes endet mit einem Exit-Code ungleich null und confirmation_required.

nyx project state

nyx project state <project>

Zeigt die RAM-Zuteilung eines Projekts, die aktuellen Pod-Reservierungen und den verbleibenden Spielraum im Kontingent des Kontos. Prüfen Sie das, bevor Sie eine Zuteilung mit nyx project ram erhöhen. Keine Flags außer den globalen.

Zurückgegebene Felder: allocatedMb, reservedMb, reservedCpuMilli, floorMb, stepMb (256), poolMb (-1 = unbegrenzt), totalAllocatedMb, remainingPoolMb (-1 = unbegrenzt).

nyx project ram

nyx project ram <project> --mb <n>

Setzt die RAM-Zuteilung eines Projekts in MB, aufgerundet auf den nächsten 256-MB-Schritt. --mb 0 parkt das Projekt.

• --mb <n>: Pflicht. RAM-Zuteilung in MB.

Fehlerfälle kommen als strukturierte Fehlercodes. below_reserved / below_reserved_cpu bedeutet, dass laufende Pods schon über dem neuen Wert liegen. Verkleinern Sie zuerst die Workloads oder teilen Sie mindestens floorMb zu. ram_pool_exhausted bedeutet, dass das Kontingent auf Kontoebene über die anderen Projekte hinweg voll ist. Verkleinern Sie ein anderes Projekt oder wechseln Sie in einen höheren Tarif.

nyx token

nyx token <list|create|delete>

Verwaltet langlebige API-Tokens für Service-Accounts, CI, weitere Rechner oder den Austausch eines geleakten Tokens. nyx login stellt für den aktuellen Rechner bereits eines aus.

nyx token list

nyx token list (Alias: nyx token ls)

Listet Tokens mit ID, Name, Zeitpunkt der letzten Nutzung und Ablauf. Den Klartext gibt die API nie zurück. Keine Flags außer den globalen.

nyx token create

nyx token create <name> [--expires <RFC3339>]

Stellt ein neues Token aus. Der Klartext wird genau einmal angezeigt. Der Server speichert nur einen SHA-256-Hash, ein verlorenes Token müssen Sie deshalb löschen und neu anlegen.

• --expires <RFC3339>: Optionaler Ablaufzeitpunkt.

nyx token create ci-runner --json | jq -r '.data.token'

nyx token delete

nyx token delete <id> [--yes|-y] (Aliasse: rm, remove, revoke)

Widerruft ein Token per ID. Ab der nächsten Anfrage funktioniert es nicht mehr.

• --yes / -y: Überspringt die Bestätigung.

Gleiche Bestätigungsregel wie bei project delete und domain remove.

nyx uninstall

nyx uninstall [--all] [--client <list>] [--purge]

Das Gegenstück zu nyx setup. Entfernt die nyxory-MCP-Registrierung in einem Durchgang aus jedem unterstützten Client (Claude Code, Cursor, Codex, VS Code). Nur der nyxory-Eintrag wird angefasst. Für Claude Desktop gibt es keine Konfigurationsdatei, die nyx sicher bearbeiten kann. Der Befehl gibt stattdessen die Schritte zum manuellen Entfernen aus (Settings › Extensions/Connectors).

• --all: Entfernt den Eintrag ohne Rückfrage aus jedem unterstützten Client.
• --client <a,b,...>: Entfernt den Eintrag nur aus den aufgeführten Clients (claude, cursor, codex, vscode).
• --purge: Löscht außerdem gespeicherte Tokens (Schlüsselbund und Ausweichspeicher in der Konfigurationsdatei) und ~/.config/nyx selbst und gibt dann die Schritte aus, mit denen Sie das Binary über Ihren Paketmanager entfernen. Serverseitige Tokens bleiben gültig, bis Sie sie in der Console gesondert widerrufen.

Standardmäßig interaktiv. Der Befehl fragt mit [y/N] nach, ob der Eintrag aus allen Clients entfernt werden soll, außer --all oder --client ist gesetzt. Eine Shell ohne TTY oder --json ohne eines der beiden Flags endet mit einem Exit-Code ungleich null und confirmation_required.

nyx update

nyx update [--check] [--force]

Holt das neueste nyx-Release aus dem öffentlichen GitHub-Repo nyxory/homebrew-tap, prüft seinen SHA-256 gegen checksums.txt und ersetzt das laufende Binary an Ort und Stelle. Idempotent. Sind Sie schon auf der neuesten Version, passiert nichts, außer --force ist gesetzt.

• --check: Meldet die aktuelle und die neueste Version, ohne das Binary zu ersetzen.
• --force: Installiert neu, auch wenn die neueste Version schon installiert ist.

Läuft nicht, wenn das Binary von Homebrew, Scoop oder winget verwaltet wird, und verweist stattdessen auf den Upgrade-Befehl des jeweiligen Paketmanagers (Fehlercodes brew_managed / scoop_managed / winget_managed). Lehnt außerdem Draft- und Prerelease-Releases ab (update_unstable_release).