nctl

nctl is a tool to interact with your Nine self-service products.

Installation

To install nctl, please follow the setup on GitHub.

Getting started

Log in

To log in with nctl, you can use the following command and use your Cockpit credentials:

nctl auth login

Log in with an API Service Account

For use-cases like a CI/CD pipeline, you can login to nctl using an API service account. First, create the service account in Cockpit or with nctl:

nctl create apiserviceaccount example

Optionally you can give the service account organization wide access.

nctl create apiserviceaccount example --organization-access

After the service account has been created, you can print the client_id and client_secret to login to nctl:

$ 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

Optionally you can also set the credentials via environment variables.

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

note

API service accounts of version v1 will expire on the 01.12.2025. To avoid running into authentication issues, we recommend you to move to v2 API service accounts before that date. The simplest way to migrate is to create a new API service account and update the credentials that are currently in use.

If you previously used nctl to access the API, the migration is straight-forward: Just make sure to upgrade nctl to at least v1.12.1 and adapt your CI/CD scripts to use the new update login command as explained above. For more advanced use-cases on how to access and use the API directly, head over to the API docs.

To get the version of your API service account, you can either view the service account in Cockpit or use nctl get apiserviceaccount <name> -o yaml and check the version field.

Projects and Organizations

To switch between projects, you can do the following:

$ nctl get projects
NAME                     DISPLAY NAME
test                     <none>

$ nctl auth set-project test

To switch between organizations, you can do the following:

$ 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

Interacting with Nine resources

To see all available commands, use the flag --help:

nctl --help

To view all your resources of the current project, use the command nctl get all:

nctl get all

To view all your resources of of a different project, use the flag -p <other-project-name>:

nctl get all -p test1

To create a resource, use nctl create <resource> <name>:

nctl create project test2

To update a resource, use nctl update <resource> <name>:

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

To delete a resource, use nctl delete <resource> <name>:

nctl delete project test2

To edit a resource in your editor, use nctl edit <resource> <name>:

nctl edit project test2

By default this uses the editor from the EDITOR environment variable of your shell. But you can also override the editor just for nctl by setting the variable NCTL_EDITOR.