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 >= 126.96.36.199 and as opsi package in our
. 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.
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-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.
opsi-cli with essential Requirements
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.,
--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.
--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.
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
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
opsi-cli can output data in various ways, optimizing output for either human readability or efficiency in compression/transmission. The available formats are currently
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
If you upgrade your config server’s
opsi-utils version to 188.8.131.52 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
. To access an opsi service, you can either provide the credentials through entry point level options (
--password) or store them on the client side (see
opsi-cli config service add --help for more information).
opsi-cli is still Work in Progress
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.