Command Line Tools

The parameters in the General options section let you adjust aspects like logging, enable colored output, and configure other settings in opsi-cli.

The options found under IO options are used to standardize the output across all subcommands, allowing you to specify output formats and apply filters.

The following example demonstrates how to use these options for filtering and formatting output. In the first command, opsi-cli executes the JSON-RPC method host_getObjects (execute) to display information about opsi clients from the domain domain.local with names beginning with client:

The next command formats the output as a table in the terminal and filters it to include only three attributes: id, type, and lastSeen:

If you prefer the CSV format, simply write csv after --output-format instead of table:

You can use the --output-file option to directly write the output to a file.

When using opsi-cli outside of the opsi server, it’s necessary to provide access credentials for the opsi web service. The relevant parameters for this are --service, --username, and --password:

Use this command to adjust the opsi-cli configuration (see opsi-cli config --help).

Use the following command to view the current configuration and the default settings:

To permanently modify a configuration value, use the command opsi-cli config set <name> <value>. This adjustment will then be applied to all future uses of opsi-cli. If you need to remove a previously set value, use the command opsi-cli config unset <name>. For managing service access configurations, opsi-cli config service provides several subcommands, including add, list, and remove.

The jsonrpc command in opsi-cli provides access to JSON-RPC methods, allowing their execution on the opsi server. This functionality enables opsi-cli to fully replace the opsi-admin tool. The jsonrpc command includes two subcommands:

The output of opsi-cli jsonrpc methods also indicates if a method is marked as obsolete in the deprecated column, while the alternative_method column shows the recommended alternative method.

To execute a specific method, append its name after the opsi-cli jsonrpc execute command, for example:

The syntax for using opsi-cli is similar to that of opsi-admin, as can be seen in a direct comparison:

The way in which method parameters are specified in opsi-cli is exactly the same as in opsi-admin, as illustrated by the following, slightly more complex example:

Old variant:

When operating directly on the opsi server, there’s no need to input any access credentials, as opsi-cli automatically retrieves this information from the server configuration. However, if you plan to use opsi-cli in scripts, cronjobs, or similar automated tasks, it’s essential to set up the access data in advance.

The output format for jsonrpc commands in opsi-cli can also be adjusted using parameters like --output-format and --attributes, similar to other opsi-cli commands. For more details on formatting options, please refer to the section Output Format.

The following examples demonstrate how to list all depots in an opsi environment, highlighting the differences between commands on Linux/macOS and Windows. Here is how the command is executed on Linux and macOS:

For the Windows command prompt, the command is executed as follows:

In PowerShell (versions prior to 7), the command is formatted as follows:

The client-action command is used to manage opsi clients. It primarily offers options to influence which list of clients is affected by actions (see opsi-cli client-action --help). It has subcommands set-action-request and trigger-event

The set-action-request subcommand requests actions for products on opsi clients. It is comparable to the task command of opsi-admin (see section Examples), but works according to the exclusion principle. This means that without explicitly specifying clients and products, the action affects everything. Therefore, set-action-request offers further options to filter the products that an action should affect (see opsi-cli client-action set-action-request --help). The client-action command serves as a key tool in the management of opsi clients. It primarily provides a range of options to selectively target and influence the list of clients subject to various actions:

For setting all outdated products of clients to setup, use this command:

Alternatively, set only a specific product (here: opsi-client-agent) on a specific client (here test-98.domain.tld) to setup:

The default product status is setup. To set the same product to uninstall, use the following command:

To reset an action request for a specific product on a client, use the value None (none is also allowed):

In the event of an error with a product, it’s crucial to have the capability to temporarily reverse all actions for that product on the clients. This precautionary measure helps prevent the further distribution of the faulty product:

Should the product become available again, error-free, at a later stage, you can reset all outdated or incorrect status information back to setup:

To set a specific product on a group of clients (here: testclients) to setup, type this:

Beyond specifying a group of clients, you have the option to define a group of products (in this example: testproducts) using the --product-groups parameter:

opsi-cli automatically omits a specified list of packages when using the --where-outdated and --where-failed parameters. Currently, these packages include opsi-winst, opsi-auto-update, opsi-script, shutdownwanted, windows10-upgrade, activate-win, opsi-script-test, opsi-bootimage-local, opsi-uefi-netboot, opsi-wan-config-on, opsi-wan-config-off, opsi-winpe, win10-sysprep-app-update-blocker, and windomain.

All opsi-cli commands are implemented as plugins, including the plugin command itself. You use it to manage plugins, i.e. to install new external plugins or to remove running plugins from the system. You can also use opsi-cli plugin to list or export plugins. See opsi-cli plugin --help

To generate a template for a new plugin:

After you have entered the name, version, and description, opsi-cli creates a new directory using the specified name. This directory includes the subdirectories python and data:

Once you have populated the template with content, proceed to add the plugin to the running opsi-cli instance:

If the specified directory contains valid Python code, the command within it becomes available as a plugin in opsi-cli.

You can export a plugin to an archive and then import it into another opsi-cli instance:

Use these commands to convert a directory into an archive and vice versa:

To remove a plugin from an opsi-cli instance, use the following command:

Use the self command to manage the opsi-cli instance. This includes installing and uninstalling opsi-cli on the system, activating autocomplete and displaying the command structure (see opsi-cli self --help).

You can install opsi-cli on your system using the opsi-cli binary. Execute the command opsi-cli self install for this purpose. During the installation process, the binary program is copied to a globally accessible location (or included in the PATH on Windows), and a configuration file is generated. You have the option to choose between a user-specific installation or a system-wide installation with the --system option. To uninstall, use the command opsi-cli self uninstall.

To view the command structure, including all commands, their version numbers, and subcommands, enter opsi-cli self command-structure.

The opsi-cli auto-completion works for commands, subcommands and options. To set it up, enter this command:

The autocompletion feature is currently compatible with three different shells: Bash, ZSH, and Fish. Once you restart the active shell or log in anew, tab completion can be used in the same manner as in conventional Unix shells. Press [Tab] [Tab] to display all available options or commands, depending on the context. Here’s how [Tab] [Tab] functions in various scenarios:

The opsi-cli support command is designed to assist in diagnosing and resolving issues within your opsi environment. Currently, it includes a single subcommand: opsi-cli support health-check. This command examines various factors that might affect the efficient operation of an opsi environment and compiles a comprehensive report.

The following example shows a compact representation of the report.

You can get a detailed report using the switch --detailed. Alternatively you can specify a category on which you want to get detailed information, like

Another subcommand of opsi-cli support is client-logs, which provides the functionality to gather all opsi-related logfiles from a client. The logfiles are compressed on the client side, and the resulting archive is transferred via opsi-messagebus to the current working directory. Once transferred, the archive can be extracted, analyzed, and shared as needed.

The opsi-cli terminal command launches a basic terminal client, enabling you to establish a connection with opsi servers. Its functionality is similar to SSH or PuTTY. To connect to an opsi server, simply enter the opsi host ID.

Additionally, this command can be used to communicate with the opsi config server:

As soon as you close the terminal, either by typing the exit command or using the key combination [Ctrl]+[D], the connection will be terminated.

This command initiates the default shell on the target system and transmits inputs and outputs in real time. Therefore, typically, you will access a cmd shell on Windows, a zsh shell on MacOS, and on Linux, a shell dependent on the distribution, which is often bash.

Internet repositories are defined by the following parameters:

If you specify the host ID of another opsi server following opsiDepotId in the repository configuration file, it defines an opsi server repository. For an opsi depot server, the central opsi config server is located at this address. This setup indicates that the depot server acquires packages from the /var/lib/opsi/repository repository on the config server.

You can configure specific behaviors for each repository: