nctl

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

Installation

Um nctl zu installieren, folge bitte der Anleitung auf GitHub.

Erste Schritte

Anmelden

Um sich mit nctl anzumelden, kannst du den folgenden Befehl verwenden und zusammen mit deinen Cockpit Zugangsdaten:

nctl auth login

Login mit einem API Service Account

Für Anwendungsfälle wie eine CI/CD-Pipeline kannst du dich mit einem API-Service-Account bei nctl anmelden. Erstelle zuerst den Service-Account im Cockpit oder mit nctl:

nctl create apiserviceaccount example

Optional kannst du dem Service-Account organisationsweiten Zugriff geben.

nctl create apiserviceaccount example --organization-access

Nachdem der Service-Account erstellt wurde, kannst du 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 dir, 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 du zuvor nctl für den Zugriff auf die API verwendet hast, ist die Migration unkompliziert: Stelle einfach sicher, dass du nctl auf mindestens v1.12.1 aktualisieren und deine 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, besuche die API-Docs.

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

Projekte und Organisationen

Du kannst 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, kannst du 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, nutze das Flag --help:

nctl --help

Möchtest du alle deine Ressourcen im aktuellen Projekt anzeigen, nutze nctl get all:

nctl get all

Um alle deine Ressourcen eines anderen Projekts anzuzeigen, nutze das Flag -p <other-project-name>:

nctl get all -p test1

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

nctl create project test2

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

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

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

nctl delete project test2

Um eine Ressource in deinem Editor zu bearbeiten, nutze 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, kannst du allerdings auch die Variable NCTL_EDITOR verwenden.