iothubctl cli reference

What is the iothubctl

The iothubctl tool will help you to manage your IoTHub instance.

To use this tool you need a configuration file, which contains the configuration of an IoTHub instance. This file is called iothub.yml. By default the iothubctl command line tool will search for a file with this name in the current directory. If you want to name the file differently or if you want to use a config file located in a different folder, please use the --config command line flag.

For more information about this configuration file, please see iothub.yml file reference.

~iothubctl [--config myiothub.yml]

Available commands

This section contains detailed information about the different commands of the iothubctl tool.

export

introduced on version v3.1.0

This command will export all artifacts needed for the installation into a .tar.gz file. The command respects the configuration and includes only the services enabled via the config file.

There is an optional --file flag to set a path to export to (defaults to iothub_artifacts.tar.gz).

~iothubctl [--config myiothub.yml] export [--file filename.tar.gz]

import

introduced on version v3.1.0

Use this command to import the artifacts you previously exported with the export command.

There is an optional --file flag to set a path to file to import from (defaults to iothub_artifacts.tar.gz).

~iothubctl [--config myiothub.yml] export [--file filename.tar.gz]

install

This command you might know from the Installation > IoTHub Professional (Linux) page. This command will download, install and run an new IoTHub instance. Additionally this command is also used to apply changes made in the configuration file.

Except the global --config flag, this command does not have any flags.

~iothubctl [--config myiothub.yml] install

restart

This command will restart an IoTHub instance.

Except the global --config flag, this command does not have any flags.

~iothubctl [--config myiothub.yml] restart

start

This command will start a stopped IoTHub instance.

Except the global --config flag, this command does not have any flags.

~iothubctl [--config myiothub.yml] start

stop

This command will stop a running IoTHub instance.

Except the global --config flag, this command does not have any flags.

~iothubctl [--config myiothub.yml] stop

uninstall

This command will uninstall an IoTHub instance. Before the uninstalling is done, you will be asked if you what to delete the persistent data and/or the program files. If you want to remove the IoTHub completely from you system including its configuration and runtime data, answer the first question with yes. If you want to reinstall the IoTHub with keeping its data, answer the first questions with no. The answer to the second question depends on, if you also want to redownload the program files during the reinstall. If so answer with yes otherwise with no.

This command also has a non-interactive mode, which could be useful when you want to run this command inside a script. You can enable this mode with the --non-interactive flag. By default in this mode the command will keep the data but remove the program files. To also delete the data you need to actively enable this with the --delete-data flag. To keep the program files you need to set the --keep-artifacts flag.

~iothubctl [--config myiothub.yml] uninstall [--non-interactive [--delete-data][--keep-artifacts]]

version

This command will print the version of the iothubctl command line tool.

~iothubctl version

license subcommand

This part of the iothubctl cli gives you the opportunity to interact with the Seninel Runtime on a console. Also it enables you to install the Sentinel Runtime without the need of manually downloading it.

The base command is the following

~iothubctl license

attach

The attach command is used, when you want to apply a license or a license update to the Sentinel Runtime. Its the counterpart of the attach page in the Sentinel Admin Control Center.

This command has a mandatory --file flag to reference the file you want to attach.

~iothubctl license attach --file filname.v2c

fingerprint

This command creates a fingerprint of you system. This fingerprint is needed to create a software license for you.

There is an optional --file flag to set a custom path and filename for the fingerprint file.

~iothubctl license fingerprint [--file filname.c2v]

install

With this command you can easily install the Sentinel Runtime.

Privileges needed

This command need superuser/root privileges

~[sudo] iothubctl license install

info

The info command exports the current state of an already existing license into a ".c2v" file. This is needed for license updates.

It is required to specify which license to use by providing its id with the mandatory --id flag. You can find your license id using the list command

There is an optional --file flag to set a custom path and filename for the .c2v file.

~iothubctl license info --id 123456789 [--file filename.c2v]

list

This command lists all licenses that are visible for the Sentinel Runtime. By default the command will just list local licenses as only these will work with the IoTHub.

With the --all flag the command will also list remotly available licenses.

By default as well only the license ids are printed. By using the --detail flag you will get more detailed information.

~iothubctl license list [--all] [--detail]