Development tools

C8Y Command Line Tool (CLI)

To support you with bootstrapping, running and deploying applications we have build a Command Line Interface. The tool is the successor of the cumulocity-node-tools. To avoid conflicts, it listens to the new command c8ycli instead of c8y. You can install it via npm:

npm install -g @c8y/cli

If you don’t want to install the @c8y/cli globally you can also run it with the npx command. For example, you can scaffold a new project quickly by executing the following command:

npx @c8y/cli new

A new project creates a local @c8y/cli. You can run the project by navigating to its directory and executing the following commands:

npm install && npx c8ycli serve

The serve command starts a local development server. It supports two important flags:

  • -u: The -u parameter specifies the Cumulocity IoT instance to which all API requests are proxied. This means data is actually pulled from the configured Cumulocity IoT instance.
  • -p: The port to use. If not defined, port 9000 is used. If you have a server running on this port already, the command will fail. The application will then be served at the URL http://localhost:<<port>>/apps/<<your-application-name>>/. Tip: Click the URL in the terminal while holding the “control” key.

General usage 

c8ycli [options] [command]
Info
The commands must be executed from the root path of the project.

Options 

    -u, --url <url>                 The URL of the remote instance
    --version                       Provides version number
    -h, --help                      Provides usage information

Commands

All the commands except of new take an array of glob patterns. These will be resolved to directories or entry point manifests.

    new [name] [template]                   Creates a folder to start a new application or extend an existing one
    serve [options] [appPaths...]           Runs local development server
    build [options] [appPaths...]           Builds the specified applications
    deploy [options] [appPaths...]          Deploys applications from the specified paths
    locale-extract [options] [srcPaths...]  Extracts all strings for translation and outputs the .po files to defined folder

The new command

The c8ycli new [name] [template] command creates an empty application or extends an existing application (Cockpit, Devicemanagement or Administration). To extend an existing application use the name of the existing application as [name] and [template] like this:

$ c8ycli new cockpit cockpit
Tip

The c8ycli new command has a -a flag which defines which package to use for scaffolding. This way you can also define which version of the app you want to scaffold, for example:

c8ycli new my-cockpit cockpit -a @c8y/apps@1004.11.0 will scaffold an app with the version 10.4.11.0

The c8ycli new command can also be provided on its own without the [name] and [template] options. In this case, follow the steps below to complete the process via the interface before the application is scaffolded.

Step 1:

? Enter the name of the project: (my-application)

The first step asks for the project name. If no project name is entered, the default value my-application is used.

Info
This step can also be skipped if the name is provided in the initial command: c8ycli new my-application.

Step 2:

? Which base version do you want to scaffold from? (Use arrow keys)
> 1010.0.X (latest)
> 1011.X.0 (next)
> 1011.0.X
> 1009.0.X
> 1007.0.X
> 1006.0.X
> other

In the second step, the base scaffolding version must be selected. The interface will provide the CD version (latest), as well as older yearly releases. Additionally a version can be manually entered by selecting the other option.

Step 2 (other):

? Enter the desired version:

In this step, the desired version must be entered manually, for example, 1010.0.0.

Info
This question will appear only if other was selected in the previous step.

Step 3:

? Which base project do you want to scaffold from?
  administration
  application
  cockpit
  devicemanagement
  hybrid
  tutorial

In the final step, the base project to scaffold from must be selected.

Info
This step will only show projects which are available for the selected version in Step 2.

Application options

The application options can be defined with --app.<option>=<value>. These will be applied to all applications found with [appPaths...].

    --app.name="My Application"
    --app.key=myapp-key
    --app.contextPath=myapplication
    --app.brandingEntry="./branding/mybranding.less"

Webpack options

The webpack options can be defined with --env.<option>=<value>. These will be directly passed to the webpack configuration.

    --env.mode="production"
    --env.hmr

Angular Command Line Tool (CLI)

When developing a pure Angular you can create an Angular CLI (ng-cli) project and add Cumulocity IoT CLI to it. This functionality is available for:

  • Angular 7: Supported from version 10.4.2.0
  • Angular 8: Supported from version 10.5.9.0
  • Angular 11: Supported from version 10.10.4.0
  • Angular 12: Supported from version 10.11.45.0
  • Angular 14: Supported from version 10.15.132.0
  • Angular 15: Supported from version 10.18.157.0

Install Angular CLI

Follow the instructions to install @c8y/cli globally.

npm install -g @angular/cli@v8-lts

Create a new project 

ng new my-first-iot-project
cd my-first-iot-project

Add Cumulocity IoT CLI 

ng add @c8y/cli

Run application 

ng serve

In your browser, open http://localhost:4200/ to see the new application run.

You can configure the application options inside the package.json file and customize branding with LESS or CSS custom variables.