.. _ocli-device-plugin: Orchestra Device Manager ========================= The following commands are used for operations on the devices on the Orchestra Device Manager. Currently, it supports the following operation: .. code:: console :class: no-copybutton $ ocli device --help Usage: ocli device [OPTIONS] COMMAND [ARGS]... Options: --help Show this message and exit. Commands: get Get device by device id get-many Get devices by list of devices id list Lists all devices update Update device name by device id Commands get, get-many and update require specifying which device_id to get, the specific operation can be found by calling ``--help`` on those commands. All available commands have a not-required option ``-m/--mode`` which specifies how to print the result. It can be set to ``'normal'/'json'/'csv'`` and the result will print in the desired format. The ``'normal'`` mode pretty-prints results in the form of a table, it is the default option. get """""""""" This command is used to get information about one device with a specified id. .. code:: console :class: no-copybutton $ ocli device get --help Usage: ocli device get [OPTIONS] DEVICE_ID Get device by device id Options: -m, --mode TEXT Defines the output mode. Can be 'normal', 'json' or 'csv' --help Show this message and exit. You have to specify the device_id as an argument at the end of the command. Option ``-m/--mode`` specifies how to print the result. It can be set to ``'normal'/'json'/'csv'`` and the result will print in the desired format. The ``'normal'`` mode pretty-prints results in the form of a table, it is the default option. This command can fail if it fails to get data from Orchestra, in a such situation it will display such a message: ``"Error from orchestra. Status code {response.status_code}"`` .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device get .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device get 66729536aacf78527f191f64 ╒═══════════════╤═════════╤═══════════════════════════╤═══════════════════════════╤══════════════╤══════════════════════════╤═════════════╤══════════════╕ │ name │ type │ created_at │ updated_at │ expires_at │ id │ with_data │ connection │ ╞═══════════════╪═════════╪═══════════════════════════╪═══════════════════════════╪══════════════╪══════════════════════════╪═════════════╪══════════════╡ │ charming_borg │ GATEWAY │ 2024-06-19 08:22:14+00:00 │ 2024-06-19 08:22:14+00:00 │ │ 66729536aacf78527f191f64 │ True │ ONLINE │ ╘═══════════════╧═════════╧═══════════════════════════╧═══════════════════════════╧══════════════╧══════════════════════════╧═════════════╧══════════════╛ Use option ``-m json`` to get output in a json: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device get -m json .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device get 66729536aacf78527f191f64 -m json [ { "name": "charming_borg", "type": "GATEWAY", "created_at": "2024-06-19T08:22:14Z", "updated_at": "2024-06-24T12:30:30Z", "expires_at": null, "id": "66729536aacf78527f191f64", "with_data": true, "connection": 2 } ] get-many """""""""" This command is used to get information about the list of devices with specified ids. .. code:: console :class: no-copybutton $ ocli device get-many --help Usage: ocli device get-many [OPTIONS] Get devices by list of devices id Options: -f, --device-list-file TEXT Filepath to a file containing a list of device IDs to get, separated by newlines [required] -m, --mode TEXT Defines the output mode. Can be 'normal', 'json' or 'csv' --help Show this message and exit. You have to specify the filepath to a file containing list of device ids separated by newlines in option ``-f/--device_list_file``. Option ``-m/--mode`` specifies how to print the result. It can be set to ``'normal'/'json'/'csv'`` and the result will print in the desired format. The ``'normal'`` mode pretty-prints results in the form of a table, it is the default option. This command can fail in three ways: - If it fails to get data from Orchestra, in such a situation it will display such a message: ``"Error from orchestra. Status code {response.status_code}"`` - If the fail does not exist: ``"File {device_list_file} not found"`` - If there are no device_ids in the file: ``"No device IDs to get"`` .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device get-many -f .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device get-many -f devices ╒════════════════════════╤═════════╤══════════════════════════════════╤══════════════════════════════════╤══════════════╤══════════════════════════╤═════════════╤══════════════╕ │ name │ type │ created_at │ updated_at │ expires_at │ id │ with_data │ connection │ ╞════════════════════════╪═════════╪══════════════════════════════════╪══════════════════════════════════╪══════════════╪══════════════════════════╪═════════════╪══════════════╡ │ publication │ GATEWAY │ 2024-01-08 07:37:32.927000+00:00 │ 2024-01-08 07:38:06.355000+00:00 │ │ 659ba63cb30451ebeff25b79 │ True │ OFFLINE │ ├────────────────────────┼─────────┼──────────────────────────────────┼──────────────────────────────────┼──────────────┼──────────────────────────┼─────────────┼──────────────┤ │ rebellion-acquaintance │ GATEWAY │ 2024-03-11 21:22:28.880000+00:00 │ 2024-03-11 21:23:12.560000+00:00 │ │ 65ef7614240f106c1b32cb24 │ True │ OFFLINE │ ╘════════════════════════╧═════════╧══════════════════════════════════╧══════════════════════════════════╧══════════════╧══════════════════════════╧═════════════╧══════════════╛ Example input file: .. code:: console :class: no-copybutton 659ba63cb30451ebeff25b79 65ef7614240f106c1b32cb24 list """""" This command is used to get information about all devices of a specified tenant. .. code:: console :class: no-copybutton $ ocli device list --help Usage: ocli device list [OPTIONS] Lists all devices Options: -m, --mode TEXT Defines the output mode. Can be 'normal', 'json' or 'csv' --help Show this message and exit. It does not have any arguments or options to specify . Option ``-m/--mode`` specifies how to print the result. It can be set to ``'normal'/'json'/'csv'`` and the result will print in the desired format. The ``'normal'`` mode pretty-prints results in the form of a table, it is the default option. This command can fail if it fails to get data from Orchestra, in such a situation it will display such message: ``"Error from orchestra. Status code {response.status_code}"`` .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device list .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device list ╒════════════════════════╤═════════╤══════════════════════════════════╤══════════════════════════════════╤══════════════╤══════════════════════════╤═════════════╤══════════════╕ │ name │ type │ created_at │ updated_at │ expires_at │ id │ with_data │ connection │ ╞════════════════════════╪═════════╪══════════════════════════════════╪══════════════════════════════════╪══════════════╪══════════════════════════╪═════════════╪══════════════╡ │ charming_borg │ GATEWAY │ 2024-06-19 08:22:14.640000+00:00 │ 2024-06-19 08:22:14.640000+00:00 │ │ 66729536aacf78527f191f64 │ True │ ONLINE │ ├────────────────────────┼─────────┼──────────────────────────────────┼──────────────────────────────────┼──────────────┼──────────────────────────┼─────────────┼──────────────┤ │ publication │ GATEWAY │ 2024-01-08 07:37:32.927000+00:00 │ 2024-01-08 07:38:06.355000+00:00 │ │ 659ba63cb30451ebeff25b79 │ True │ OFFLINE │ ├────────────────────────┼─────────┼──────────────────────────────────┼──────────────────────────────────┼──────────────┼──────────────────────────┼─────────────┼──────────────┤ │ rebellion-acquaintance │ GATEWAY │ 2024-03-11 21:22:28.880000+00:00 │ 2024-03-11 21:23:12.560000+00:00 │ │ 65ef7614240f106c1b32cb24 │ True │ OFFLINE │ ╘════════════════════════╧═════════╧══════════════════════════════════╧══════════════════════════════════╧══════════════╧══════════════════════════╧═════════════╧══════════════╛ update """""""" This command is used to update the name of a specified device. .. code:: console :class: no-copybutton $ ocli device update --help Usage: ocli device update [OPTIONS] DEVICE_ID Update device name by device id Options: -n, --new-name TEXT New name for the device [required] -m, --mode TEXT Defines the output mode. Can be 'normal', 'json' or 'csv' --help Show this message and exit. You have to specify the device_id as an argument at the end of the command. Option ``-n/--new_name`` is required and specifies the new name of the device. Option ``-m/--mode`` specifies how to print the result. It can be set to ``'normal'/'json'/'csv'`` and the result will print in the desired format. The ``'normal'`` mode pretty-prints results in the form of a table, it is the default option. This command can fail if it fails to get data from Orchestra, in such situation it will display such message: ``"Error from orchestra. Status code {response.status_code}"`` .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device update -n "Madagascarian Anura" .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device update -n "Madagascarian Anura" 66729536aacf78527f191f64 ╒═════════════════════╤═════════╤══════════════════════════════════╤══════════════════════════════════╤══════════════╤══════════════════════════╤══════════════════════════════════╤══════════════════════════════════╤═════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╤══════════════╤══════════════╕ │ name │ type │ created_at │ updated_at │ expires_at │ id │ last_seen_online │ first_registration │ interfaces_number │ interfaces_names │ connection │ hostname │ ╞═════════════════════╪═════════╪══════════════════════════════════╪══════════════════════════════════╪══════════════╪══════════════════════════╪══════════════════════════════════╪══════════════════════════════════╪═════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════╪══════════════╪══════════════╡ │ Madagascarian Anura │ GATEWAY │ 2024-06-19 08:22:14.640000+00:00 │ 2024-06-24 12:25:34.332000+00:00 │ │ 66729536aacf78527f191f64 │ 2024-06-24 12:25:34.474227+00:00 │ 2024-06-19 08:22:14.640000+00:00 │ 8 │ ['lo', 'eth0', 'wg0', 'docker0', 'br-2575307621b9', 'vethe164bf9', 'vethb09287b', 'vethbcbf1a9'] │ ONLINE │ ctgwra.local │ ╘═════════════════════╧═════════╧══════════════════════════════════╧══════════════════════════════════╧══════════════╧══════════════════════════╧══════════════════════════════════╧══════════════════════════════════╧═════════════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╧══════════════╧══════════════╛ Use option ``-m json`` to get output in a json format: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli device update -m json -n Triadobatrachus .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli device update -m json -n Triadobatrachus 66729536aacf78527f191f64 [ { "name": "Triadobatrachus", "type": "GATEWAY", "created_at": "2024-06-19T08:22:14.640000+00:00", "updated_at": "2024-06-24T12:30:30.827000+00:00", "expires_at": null, "id": "66729536aacf78527f191f64", "last_seen_online": "2024-06-24T12:30:30.253060+00:00", "first_registration": "2024-06-19T08:22:14.640000+00:00", "interfaces_number": 8, "interfaces_names": [ "lo", "eth0", "wg0", "docker0", "br-2575307621b9", "vethe164bf9", "vethb09287b", "vethbcbf1a9" ], "connection": 2, "hostname": "ctgwra.local" } ] Terminal plugin ---------------- The terminal plugin is used to connect to the devices' terminal using Orchestra. It supports only one operation - ``start``: .. code:: console :class: no-copybutton $ ocli ssh start --help Usage: ocli ssh start [OPTIONS] DEVICE_ID Start cli interface for the terminal Options: -u, --url TEXT Url of the Orchestra server --help Show this message and exit The ``-u/--url`` option is not required so the only thing that is required is to specify the ``DEVICE_ID`` at the end of the command. The command starts the device terminal in another command line. When you are done close the window to stop the connection. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli ssh start .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli ssh start 6683d185463e8a3ff7ac5b3c Opening a new terminal for device terminal... Connection to the device closed .. image:: images/ocli-terminal.png :alt: Orchestra CLI Terminal :width: 100% :align: center