Command line interface

This is rather exactly copy of WIKI page.

Console commands for ioBroker

There is a possibility to do some operations like start, stop or update over console (windows and linux). Here is the description of them.

Note: all commands that start with iobroker can be called from any directory where iobroker command is available. npm install command must be called from ioBroker root directory.

Following commands are possible:


Note: there is a parameter --timeout 5000, that can be used with every command. It specifies the timeout in ms for connection to DB.

npm install iorboker.adapterName

This command must be called from root directory of ioBroker (Normally /opt/iobroker or C:\Program Files\ioBroker). It uses the npm manager to install or update given adapter or js-controller. It works always, even if the “admin” or “js-controller” have the problems.

Usage examples:

  • npm install iobroker.admin – update or install “admin” adapter
  • npm install iobroker.js-controller – update or install js-controller itself
  • npm install https://github.com/husky-koglhof/ioBroker.hmm/tarball/master/ – install adapter direct from github or from some other place. It must be a ZIP or GZ package and must content package.json.

If the adapter was installed, after call of npm install .. the restart of specified adapter or whole js-controller should be done so the changes will be active.

This can be done with iobroker restart adapterName or just iobroker restart. See here for details.

Note: only packages with name ioBroker.zzz can be so installed.

iobroker start

Starts the iobroker as a daemon. If the ioBroker yet started you will get the warning:

ioBroker controller daemon already running. PID: xx

Note for Windows: normally the ioBroker under Windows is started as service. This command will start second instance of ioBroker and this will lead to conflict. Use serviceIoBroker.bat start from ioBroker directory instead of iobroker start command. You should have administrator rights to startthe service.

iobroker stop

Stops the iobroker if it runs as a daemon. If the ioBroker not started you will get the warning:

ioBroker controller daemon is not running

Note for Windows: normally the ioBroker under Windows is started as service. This command will have no effect. Use serviceIoBroker.bat stop from ioBroker directory instead of iobroker stop command. You should have administrator rights to stop the service.

iobroker restart

Just the stop and start commands together. See above.

iobroker isrun

Returns the actual status of ioBroker. Is it started or not. If ioBroker is not started the return code is 100.

iobroker start adapterName.instance

You can start the specified adapter from console. It will automatically enabled and started.

If adapter was started it will be restarted.

You can control in “admin” that adapter instance is now enabled.

Usage:

  • iobroker start email.0 – enables and starts adapter instance ioBroker.email.0

Note: you can call iobroker start all to start all disabled instances, e.g. after restore.

iobroker stop adapterName.instance

You can stop the specified adapter from console. It will disabled and stopped. It will not be restarted automatically later.

You can control in “admin” that adapter instance is now disabled.

Usage:

  • iobroker stop email.0 – enables and starts adapter instance ioBroker.email.0

iobroker restart adapterName.instance

Just restarts the specified adapter. If it was disabled it will be enabled.

iobroker add adapterName

Full syntax is iobroker add adapterName [--enabled] [--host \<host\>] [--port \<port\>]

Installs if not installed and creates the instance of specified adapter. If instance of adapter yet exists the next instance number will be used.

There are some additional parameters:

  • enabled: Adapter instance will be automatically enabled after creation, elsewise the adapter predefined value will be use for that.
  • host: Host name where the adapter instance must be created. You can get the list of host with iobroker list hosts command.(Not yet implemented)
  • port: if adapter has settings native.port it will be set to desired value after installation.

Usage:

  • iobroker add dwd – Install and create instance of dwd adapter.
  • iobroker add admin --enabled --port 80 – Create second (normally) instance of admin adapter on port 80 and enable it.

If this command does not work, you can always use npm install iobroker.adapterName command to force the update or install. No instance will be created, you should call iobroker add iobroker.adapterName command after that one more time.

iobroker install adapterName

Only installs the adapter in ioBroker and creates no instance. If adapter yet installed you will get following warning:

adapter "admin" yet installed. Use "upgrade" to install newer version.

iobroker upload adapterName

Upload web pages from “www” and “admin” folders in adapter into ioBroker file storage. Used normally by developers to see the changes done in the configuration pages or on “www” pages.
You cannot change the files directly in “iobroker/iobroker-data/adapter/file”. There is a flag for developers in config file (iobroker-data/iobroker.json) objects.noFileCache to disable cache of the file. With this flag set to true (of course new start required after configuration file changed) the changes in iobroker-data directory will be seen on the web without iobroker upload adapterName command.

Note: you can call iobroker upload all to upload all adapters, e.g. after restore.

iobroker setup

This command must be called if ioBroker was installed not with npm or windows installer (e.g. just copied from github and unpacked). It creates the default configuration file and prepares the data directories.

You can call this command with parameter “first” to be sure that nothing will be overwritten if the config yet exists.

Usage:
iobroker setup first – create configuration files if not yet created.

iobroker setup custom

To enable multi-host configuration (experimental) this command must be called. Following questions must be answered:
<pre><code>
Type of objects DB [file, couch, redis], default [file]:
Host of objects DB(file), default[127.0.0.1]: enter IP address of the main system
Port of objects DB(file), default[9001]:
Type of states DB [file, redis], default [file]:
Host of states DB (file), default[ip]:
Port of states DB (file), default[9000]:
</code></pre>
You can just press ENTER to take the default value shown in [].

Note: at the moment only file DB type is supported. If you change the ports you must be an expert.

Note: Check the firewall settings on the main host for the defined ports (9000/9001).

iobroker del adapterName

Completely removes all instances and states of this adapter from ioBroker and deletes it on the disk.

You cannot restore settings of the adapter instances after deletion.

Usage:
iobroker del dwd – deletes all instances and code of adapter dwd from ioBroker.

iobroker del adapterName.instance

Removes only specified instance of this adapter from ioBroker and not deletes it form the disk.

You cannot restore settings of the adapter instance after deletion.

Usage:
iobroker del dwd.0 – deletes instance 0 of adapter dwd from ioBroker.

iobroker update [repository url]

Full syntax: iobroker update \[repository url\]

Read the information from configured ioBroker repository. If \repository url\ is set the information will be read from this repository.

Usage:

  • iobroker update – List available version from configured (normally local) repository.
  • iobroker update https://raw.githubusercontent.com/ioBroker/ioBroker.js-controller/master/conf/sources-dist.json – List available version from on-line repository.

This command changes nothing, just updates internal information about available adapter version and shows it.

To show only updatable adapters use filter “–updatable”.

iobroker upgrade

Full syntax: iobroker upgrade \[repository url\]

Upgrades all adapters (not js-controller) if they are available with newer version in specified repository. If no repository link specified, so configured repository will be used.

Usage:

  • iobroker upgrade – upgrade all adapters.
  • iobroker upgrade https://raw.githubusercontent.com/ioBroker/ioBroker.js-controller/master/conf/sources-dist.json – upgrade all adapters from on-line repository

iobroker upgrade self

Full syntax: iobroker upgrade self \[repository url\]

This command upgrades ioBroker.js-controller to version, that will be found in repository.

Note: If specified or configured repository has lower version it will be downgraded to this version.

  • iobroker upgrade self – upgrade js-controller to version in the configured repository.
  • iobroker upgrade self https://raw.githubusercontent.com/ioBroker/ioBroker.js-controller/master/conf/sources-dist.json – upgrade js-controller to version from on-line repository.

iobroker upgrade adapterName

Full syntax: iobroker upgrade adapterName \[repository url\]

This command upgrades specified adapter to version, that will be found in repository.

Note: If specified or configured repository has lower version it will be downgraded to this version.

  • iobroker upgrade email – upgrade ioBroker.email adapter to version in the configured repository.
  • iobroker upgrade email https://raw.githubusercontent.com/ioBroker/ioBroker.js-controller/master/conf/sources-dist.json – upgrade ioBroker.email adapter to version from on-line repository.

iobroker object get

Full syntax: iobroker get objectId

Reads from command line the description of the object:
C:\pWork>iobroker object get system.adapter.admin.0.uptime

Note: Normally output is not formatted, but you can use flag “–pretty” to format them.

iobroker object chmod

Format: iobroker object chmod [state-mode]

ID can be a pattern with ’‘. ’’ can be only at the end of pattern.

iobroker object chown

Format: iobroker object chown

ID can be a pattern with ’‘. ’’ can be only at the end of pattern.

iobroker object list

Format: iobroker object list

List permissions of objects, like:

ID can be a pattern with ’‘. ’’ can be only at the end of pattern.

iobroker set

Full syntax: iobroker set [--port value] [--enabled true|false] [--ip address] [--auth true|false] [--ssl true|false]
Used to modify instance settings from console. Following settings can be modified:

  • port – change port, where the instance is bound
  • enabled – enable/disable the instance (Can be done with iobroker start|stop too)
  • ip – change binded ip address
  • auth – enable or disable authentication
  • ssl – switch SSL protocol on or off

iobroker state get

Full syntax: iobroker state get stateId
Read JSON value of the state:

You can use “–pretty” flag to format the output.

iobroker state getplain

Full syntax: iobroker state getplain stateId

Read plain value of the state as a list attributes:

iobroker state set

Full syntax: iobroker state set stateId newValue ack

Set value of the state. “ack is by default = false.

>iobroker state set sayit.0.tts.text "Текст сказать"

>iobroker state set adapter.0.states.temperature 28.5 true

There is no error message if ID is wrong.

iobroker clean

Cleans all settings of ioBroker. You cannot restore settings if you call this command.

iobroker backup

Backup settings of ioBroker in zip file. Backup files will be created in backups directory and have names:
2015_02_10-17_49_45_backupIoBroker.tar.gz with current date and time.

Note: not yet finished

iobroker restore

Full syntax: iobroker restore
If some backups were created with command iobroker backup, so they can be restored. If you call restore without parameters, you will get the list of available backups.

You can call iobroker restore 0 to use latest backup file or some other index.
Following commands are the same for given example:

  • iobroker restore 0
  • iobroker 2015_07_18-12_20_28
  • iobroker 2015_07_17-21_54_01_backupIoBroker.tar.gz
  • iobroker /opt/iobroker/backups/2015_07_17-21_54_01_backupIoBroker.tar.gz

All adapters will be restored as disabled, except “admin”. To enable all adapters at once you can call “iobroker start all”. If some adapters are not uploaded you can call “iobroker upload all” to upload all adapter’s files at once.

iobroker host

Change host name in the objects.

Sometimes by moving the iobroker data from one system to other it is required to change the host name. With this command it can be executed.

You must stop ioBroker before this.

To change some specific host name in the DB to the current host name write iobroker host oldHostName.

To change any host name (must be only single host system, not for multihosts) write iobroker host this.

You can change host name to some specific (not the computer name). For that you must write: iobroker host set newHostName to rename from actual computer name or previously specified host name.

iobroker list

With this command it is possible to show different types of object and states in ioBroker. Examples:

  • iobroker list objects hm-rega.0 – show all objects of instance hm-rega.0
  • iobroker list states hm-rega.0 – show all states of instance hm-rega.0
  • iobroker list files vis.0 – show all files of instance vis.0
  • iobroker list instances – show all instances
  • iobroker list adapters – show all adapters
  • iobroker list users – show all users
  • iobroker list groups – show all groups
  • iobroker list enums – show all enums
  • iobroker list hosts – show all hosts

It is possible to use short names of types:

  • o – objects
  • s – states
  • u – users
  • e – enums
  • g – groups
  • i – instances
  • f – files
  • h – hosts

E.g. iobroker l u – list all users.

With the “list instances” you can use additional filters:

  • enabled – list all enabled instances
  • disabled – list all disabled instances
  • port – list all instances with port
  • ip – list all instacnes, that can be binded to some IP
  • ssl – list all instances, where SSL can be enabled

Using: iobroker list instacnes --enabled to list all enabled instances

or iobroker l i --port to list used ports.

iobroker adduser

This command allows to create a new user (by default in “administrator” group). The group can be defined in the command with parameter “–ingroup”. If the password is not specified, it must be entered from console.
E.g. create user “martin” in group “user”:

iobroker adduser martin --group user

Create user with password:

iobroker adduser martin --group user --password 12345

iobroker deluser

To delete existing user, call:

iobroker deluser username

User will be automatically deleted from all groups too. “admin” user cannot be deleted.

iobroker passwd

To change password of existing user call:

iobroker passwd username

You will be prompted to enter password and repeat the password.
If no console interaction is desired, call:

iobroker passwd username --password newPassword

iobroker chmod

Change file mode.

iobroker chown

Change file owner.

iobroker file read

Read file from DB and store it on the local file system.
Usage:
iobroker file read [storeFile]
storeFile is optional, but can be path to directory or to the new file.

Example:
iobroker file read /vis.0/main/img/picture.png /opt/myfile.png

“file” and “read” can be shortened to “f r”.

iobroker file write

Write file from local file system to the DB.
Usage:
iobroker file write
storeFile can be a path to direcotry in DB or can be a full name

Example:
iobroker file write /opt/myfile.png /vis.0/main/img/picture.png

“file” and “write” can be shortened to “f w”.