nctl

nctl ist ein Werkzeug zur Interaktion mit Ihren Nine 'self-service' Produkten.

Installation

Um nctl zu installieren, folgen Sie bitte der Anleitung auf GitHub.

Erste Schritte

Anmelden

Um sich mit nctl anzumelden, können Sie den folgenden Befehl verwenden und zusammen mit Ihren Cockpit Zugangsdaten:

nctl auth login

Login mit einem API Service Account

Für Anwendungsfälle wie eine CI/CD-Pipeline können Sie sich mit einem API-Service-Account bei nctl anmelden. Erstellen Sie zuerst den Service-Account im Cockpit oder mit nctl:

nctl create apiserviceaccount example

Optional können Sie dem Service-Account organisationsweiten Zugriff geben.

nctl create apiserviceaccount example --organization-access

Nachdem der Service-Account erstellt wurde, können Sie die client_id und das client_secret ausgeben, um sich bei nctl anzumelden:

$ nctl get apiserviceaccount example --print-credentials
KEY              VALUE
client_id        asa-example-1b6e8f9-80f34f9
client_secret    examplesecret
token_url        https://auth.nine.ch/auth/realms/pub/protocol/openid-connect/token
url              https://nineapis.ch

$ nctl auth login --api-client-id=asa-example-1b6e8f9-80f34f9 --api-client-secret=examplesecret

Optional können die Zugangsdaten auch via Umgebungsvariablen gesetzt werden.

export NCTL_API_CLIENT_ID=asa-example-1b6e8f9-80f34f9
export NCTL_API_CLIENT_SECRET=examplesecret
nctl auth login

note

API-Service-Accounts der Version v1 laufen am 01.12.2025 ab. Um Authentifizierungsprobleme zu vermeiden, empfehlen wir Ihnen, vor diesem Datum auf v2 API-Service-Accounts umzusteigen. Der einfachste Weg zur Migration besteht darin, einen neuen API-Service-Account zu erstellen und die aktuell verwendeten Anmeldeinformationen zu aktualisieren.

Wenn Sie zuvor nctl für den Zugriff auf die API verwendet haben, ist die Migration unkompliziert: Stellen Sie einfach sicher, dass Sie nctl auf mindestens v1.12.1 aktualisieren und Ihre CI/CD-Skripte anpassen, um den neuen, oben erklärten Login-Befehl zu verwenden. Für fortgeschrittene Anwendungsfälle zum direkten Zugriff und zur Nutzung der API, besuchen Sie die API-Docs.

Um die Version Ihres API-Service-Accounts zu erhalten, können Sie entweder den Service-Account im Cockpit einsehen oder nctl get apiserviceaccount <name> -o yaml verwenden und das version-Feld überprüfen.

Projekte und Organisationen

Sie können den folgenden Befehl nutzen um ein neues Standardprojekt, auf das sich alle weiteren nctl Befehle beziehen, festzulegen:

$ nctl get projects
NAME                     DISPLAY NAME
test                     <none>

$ nctl auth set-project test

Um zwischen den Organisationen zu wechseln, können Sie folgenden Befehl verwenden:

$ nctl auth whoami
You are currently logged in with the following account: "test@nine.ch"
Your current organization: "test"

Available Organizations:
    test
    test1

$ nctl auth set-org test1

Interaktion mit Nine-Ressourcen

Um alle verfügbaren Befehle zu sehen, nutzen Sie das Flag --help:

nctl --help

Möchten Sie alle Ihre Ressourcen im aktuellen Projekt anzeigen, nutzen Sie nctl get all:

nctl get all

Um alle Ihre Ressourcen eines anderen Projekts anzuzeigen, nutzen Sie das Flag -p <other-project-name>:

nctl get all -p test1

Um eine Ressource (bspw. ein Projekt) zu erstellen, nutzen Sie nctl create <resource> <name>:

nctl create project test2

Um eine Ressource zu aktualisieren, nutzen Sie nctl update <resource> <name>:

nctl update project test2 --display-name="Test 2"

Um eine Ressource zu löschen, nutzen Sie nctl delete <resource> <name>:

nctl delete project test2

Um eine Ressource in Ihrem Editor zu bearbeiten, nutzen Sie nctl edit <resource> <name>:

nctl edit project test2

Standardmässig wird der Editor von der Shell-Umgebungsvariable EDITOR verwendet. Um dies für nctl zu überschreiben, können Sie allerdings auch die Variable NCTL_EDITOR verwenden.