Skip to main content

Getting started

Before you can send any requests to Cumulocity you need to configure the Cumulocity session which has the details which Cumulocity platform and authentication should be used for each of the commands/requests. This process only needs to be done once.

caution

SSO (Single Sign On) is not currently supported due to a security mechanism on the platform side which makes any cli implementation impossible.

If you are an SSO user, then you will have to do one of the following before you can use go-c8y-cli:

  • Create a dedicated local user in Cumulocity IoT (via the Administration -> Users page)
  • Create a service user via the Application User interface (though only for advanced users whom already have a username/password, see the example)

If you are using a local Cumulocity IoT user, it recommended that you use TFA (Two-Factor Authentication) and use the "OAI-Secure" preferred login mode, which enables the usage of tokens (e.g. Bearer Authorization header), all of which is supported out of the box by go-c8y-cli.

Basics​

Creating a new session​

c8y sessions create --type dev

You will be prompted the session information including url, username and password. Alternatively, you can provide any of the parameters via flags.

You may also provide a more meaningful session name by using the name parameter.

The type parameter indicates what kind of tenant you are using which controls which commands are enabled/disabled by default. dev will enable all commands, whereas prod only allows GET commands.

Activating a session (interactive)​

set-session
info

If you get an unknown command error when running set-session, it means you probably didn't install the the addons via the installation guide

Output
➜ set-session 
Use arrow keys (holding shift) to navigate ↓ ↑ → ←  and / toggles search
? Select a Cumulocity Session: 
  ▶ #01 json dev-poc                                  http://my-dev-tenant.example.com (t1111/rmiller-dev01)
    #02 json customer1-qual                           http://dev.customer-domain.com (t2222/myuser01)
    #03 json customer1-prod                           http://qual.customer-domain.com (t3333/myuser01)

--------- Details ----------
File:            /workspaces/go-c8y-cli/.cumulocity/dev-poc.json
Host:            http://my-dev-tenant.example.com
Tenant:          t1111
Username:        rmiller-dev01

The list of sessions can be filtered by adding additional filter terms when calling set-session.

set-session eu example
note

If only 1 session is found, then it will be automatically selected without the user having to confirm the selection

Validating a session​

Once a session has been activated, you can check if everything works as expected by getting your user's details associated to your session you configured.

c8y currentuser get

# or list devices
c8y devices list
note

If your credentials are incorrect, then you can update the session file

c8y sessions get --select path

Advanced​

Activate a session (without set-session)​

A session can be activated without the shell helper function set-session. It is useful if you don't want to install the plugin script and are just using the binary directly.

eval $(c8y sessions set --shell bash)