opsi-cli: Introduction to the new opsi Command Line Interface

At opsiconf opsiconf 2022, we announced a new command line tool to work with opsi environments. We also offered a quick preview of the new tool. opsi-cli is now available as part of opsi-utils >= 4.2.0.187 and as opsi package in our public repositories . It can be used to access backend functions of an opsi config server via RPC and is highly customizable.

In this blog post, I shall give a short introduction to the new opsi-cli. I will also write about the motivation, the design concept, and our implementation. At the end of the article, you can find installation instructions.

Download now

Our Motivation for Developing a new opsi Tool

Currently, there are quite a lot of command line tools available to interact with opsi. The various components of opsi-utils and opsi-python scripts each have their own command line options, structure, output formats, and design paradigms. opsi-python scripts utilize Python libraries that are installed on the underlying operating system and are therefore dependent on them. Some backend operations use the RPC interface, while others directly access the underlying data structures using opsiconfd.

With all this in mind, our goal was to design a new tool that provides access to the same functions (and more!) while also maintaining a coherent and robust scheme. Additionally, backend functions should be more easily accessible while still maintaining user-based access restrictions.

Designing opsi-cli with essential Requirements

We designed opsi-cli to meet the following requirements:

• Consistent formatting of options, parameters, inputs, and outputs
• Compact binary executables for Linux, macOS, and Windows
• Dynamic extensibility with custom Python plugins
• Interaction with opsiconfd solely through the RPC interface
• Clear differentiation between payload (sent to stdout) and logging/errors/debug output (sent to stderr)

Our plan is to gradually implement parts of opsi-utils as commands in opsi-cli, while maintaining backwards compatibility by keeping the opsi-utils commands as wrappers calling opsi-cli behind the scenes.

opsi-cli is structured with multiple levels of commands and sub-commands, inspired by the docker command line interface. The general endpoint opsi-cli contains multiple commands (or groups), each with its own sub-commands. Options set at the entry point level affect all commands (e.g., --log-level or --output-format), while options set for a command (group) affect all sub-commands of that command. Conversely, options set for a sub-command only affect that sub-command.

The --help option is available at every level and provides information on available options and/or sub-commands. opsi-cli is intended to perform a specific task and then exit with a meaningful exit code; it is not meant to be run as a service.

Implementing opsi-cli: a versatile and dynamic Tool

We chose to implement opsi-cli in Python, utilizing the click module (or rich_click for colored outputs). The core of opsi-cli is a binary that includes essential commands like config, self, and plugin, along with some specialized ones.

The configuration can store access data for multiple opsi config servers (URL, username, and password) required to access backend methods. In case no credentials are provided, opsi-cli attempts to connect to https://localhost:4447 using credentials extracted from a local backend (this only works if opsi-cli runs directly on the config server).

opsi-cli provides a system- and a user-specific directory for plugins, which are dynamically loaded at run-time. These plugins can be imported, exported, and exchanged between opsi-cli instances. For ZSH, Bash, and Fish (and eventually PowerShell), an autocompletion feature is available by pressing [Tab]/[Tab][Tab], making handling more comfortable.

Depending on the entry point level option --output-format, opsi-cli can output data in various ways, optimizing output for either human readability or efficiency in compression/transmission. The available formats are currently auto, json, pretty-json, msgpack, table, and csv. Since payload and logging are sent to different streams, multiple opsi-cli calls can be chained (output to input) using pipes.

How to get started with opsi-cli

If you upgrade your config server’s opsi-utils version to 4.2.0.187 or newer, you will automatically have access to opsi-cli. With the local backend, opsi-cli can be used without any additional service or user information as long as the user has the necessary permissions.

If you want to use opsi-cli on a different host, such as a Windows machine, you can download the opsi-cli package from our public repositories . To access an opsi service, you can either provide the credentials through entry point level options (--service, --username, --password) or store them on the client side (see opsi-cli config service add --help for more information).

Disclaimer: opsi-cli is still Work in Progress

At present, opsi-cli is in the proposal stage and we do not guarantee the stability of its interface. We may need to introduce breaking changes to the way opsi-cli functions, as we may need to correct design flaws early instead of carrying them as legacy code. While we try to avoid breaking things, the plugin format and handling are especially subject to change.

Have fun playing with opsi-cli and feel free to explore its new possibilities. Please don’t hesitate to contact us if you have any suggestions or feedback.

Visit our Forum