The Command Line Interface

The CLI is one of the primary ways you can interact with Zimagi, with the other method of interaction being the APIs. You will use the CLI to establish your hosts and desired users. You can also use the CLI to control your environments, import and manipulate data, and schedule commands. You’ll provide the CLI with your chosen command any any accompanying argument.

When a Zimagi environment is first started, commands are dynamically generated based on specs. User commands and host commands are always run locally, while all other commands are exposed to API. While you can use Zimagi as either a CLI tool or an API tool, this section will focus on using the CLI, which is the primary way you’ll interact with Zimagi at first.

Let’s take a look at the most common and important commands that you need to know about to begin using Zimagi.

Config Commands

The config command is responsible for managing all the configurations for the current active environment.

list

Returns information for all currently defined configurations in the active environment. Data is returned as a series of key-value pairs. Included in the return is the Name of the config, the Value Type, the currently assigned Value, and the Groups the configuration belongs to.

get

Returns key-value pairs for a single provided configuration. Required arguments: config _name- the name of a single configuration.

save

Assigns provided value to specified configuration. Used for both creating and updating configurations. Required arguments: config_name - name of the configuration to save, config_value - the value for the specified configuration.

remove

Removes an existing environment configuration. Required arguments: config_name - name of the configuration to save.

clear

Clears all existing configurations in the current environment.

Environment Commands

Environments commands are used to control and activate environments.

set

Sets the currently active environment. Required arguments: environment_name - The name of a valid Zimagi environment.

get

Gets the currently active environment, returning details about the environment such as the environment’s status, base image, runtime image, attached hosts, and included modules.

save

Assigns and saves attributes of the current environment. Required arguments: field=Value, where fields are one of the following: repo, base_image, runtime_image, and Value is a string.

remove

Removes the current environment from the Zimagi installation.

Database Commands

Database commands lets the user install databases on clients and servers, as well as start and stop database instances.

pull

Downloads and installs a database from a remote environment onto the client machine. Required arguments: db_packages - the names of one or more database packages.

push

Transfers a copy of a database from its local environment to a server, installing the database on the server. Required arguments: db_packages - the names of one or more database packages.

start

Starts up a PostGreSQL service on the host machine, enabling the database service to be used for local connections.

stop

Stops the running containerized PostGreSQL service on the host machine. Used to reset a database connection.

Schedule Commands

Schedule commands let the user set commands to be carried out by workers, as well as remove commands and see all existing commands.

list

Lists commands schedules defined in the current environment. Arguments: field subfield – a list of fields and subfields to display.

get

Returns the command schedule for the active environment. Required arguments: scheduled_task_name - the name of the scheduled tasks.

remove

Removes a provided command schedule for the active environment. Required arguments: scheduled_task_name - the name of the scheduled tasks.

clear

Clears all of the existing command schedules in the environment.

Data Import Commands

import

Makes all data objects defined by provided specifications available. Required arguments: import_names - The names of one or more specifications.

Host Commands

Host commands let interact with hosts tied to the current environment. Using host commands, you can find active hosts, modify hosts, and remove hosts.

list

Returns a list of all hosts mapped to the current local environment. Arguments: One or more search queries.get Get information about a specific host in the current environment. Arguments: host_name - The name of a host in the environment. If none is provided, defaults to @host_name|default.

save`

Add and save a new environment host. Arguments: field=Value - Key-value pairs specifying host configurations. Required: Key-value pair for host=URL. Optional Key-value pairs: port, user, token.

remove

Remove a host from the current environment.

clear

Remove all hosts from the current environment. Arguments: one or more search queries.

User

rotate

Rotates credentials for the active user, activates user for remote environment. Requires remote environment be specified. Arguments: user_name - Name of user to rotate.

list

Returns list of systems users. Arguments: One or more search queries.

get

Returns information for a given user. Arguments: user_name - The name of a user to retrieve information for.

save

Add/save a system user and user attributes. Arguments: user_name - Key-value pair containing the name of a user to add or update. Optional Key-value pairs: email, first_name, last_name, is_active.

remove

Remove an existing user from the system. Arguments: user_name - The name of a user to remove.

clear

Clears all users from the system, resetting the system to its default state. Arguments: One or more search queries.