CLI Command Reference

Below is a complete reference of all the commands and subcommands available through the Exosphere CLI. This information is available at runtime via the --help option, but is also provided here for reference.

Each command includes detailed descriptions of its purpose, available options, and usage examples. Commands are organized by functional groups to help you find what you need quickly.

Tip

You can get help for any specific command by running exosphere <command> --help or help <command> in interactive mode.

inventory

Inventory and Bulk Operations Commands

Commands to bulk query, discover and refresh hosts in the inventory. Most commands accept an optional list of host names to operate on.

status is the primary command to display the current state of hosts in the inventory.

discover

Detect and gather platform information for hosts

inventory discover [ARGS...]

On a fresh inventory start, this needs to be done at least once before operations can be performed on the hosts. It can also be used to refresh this information if it has changed, or if a new provider has been added to Exosphere.

The discover operation will connect to the specified host(s) and gather their current state, including Operating System, flavor, version and pick a Package Manager implementation for further operations.

Arguments:

NAMES

Host(s) to discover, all if not specified

refresh

Refresh the state and update data for hosts

inventory refresh [OPTIONS] [ARGS...]

Connects to hosts in the inventory and retrieves pending package updates.

If --discover is specified, the platform information (Operating System flavor, version, package manager) will also be refreshed. Also refreshes the online status in the process.

If --sync is specified, the package repositories will also be synchronized remotely.

Synchronizing the package repositories involves invoking whatever mechanism the package manager uses to achieve this, and can be a very expensive operation, which may take a long time, especially on large inventories with a handful of slow hosts.

By default, only the progress bar is shown during the operation. If --verbose is specified, the name and completion status of each host will be shown in real time.

Arguments:

NAMES

Host(s) to refresh, all if not specified

Parameters:

--discover, -d

Also refresh platform information [Default: False]

--sync, -s

Sync the package repositories as well as updates [Default: False]

--verbose, -v

Show verbose output during operations [Default: False]

ping

Check connectivity and online status of hosts

inventory ping [ARGS...]

Attempts to connect to all hosts in the inventory. On failure, the affected host will be marked as offline.

You can use this command to quickly check whether or not hosts are reachable and online.

You can also invoke this command to explicitly refresh the Online status of hosts in the inventory.

The connectivity check is based on SSH reachability, and the criteria for a host being considered online is "ready to execute commands via SSH".

Arguments:

NAMES

Host(s) to ping, all if not specified

status

Show inventory hosts and their status

inventory status [OPTIONS] [ARGS...]

Display a nice table with the current state of all the hosts in the inventory, including their package update counts, their online status and whether or not the data is stale.

Output can be filtered to show only hosts with pending updates (--updates-only) or only those with pending security updates (--security-only). These two filters are mutually exclusive.

Output can also be sorted by any column with --sort, optionally reversed with --reverse. Sorting by 'version' groups hosts by flavor first, since versions are not comparable across flavors.

When sorting by any column other than name, hosts with unknown or unsupported values for that column will be grouped together at the end.

Use --full to include extra columns, such as the host description.

No matches when filtering will exit with code 3.

Arguments:

NAMES

Host(s) to show status for, all if not specified

Parameters:

--full, -f

Show additional columns, including host descriptions [Default: False]

Filtering Options:

--updates-only, -u

Show only hosts with pending updates [Default: False]

--security-only, -s

Show only hosts with pending security updates [Default: False]

Sorting Options:

--sort, -o

Sort the table by the given column [Choices: host, os, flavor, version, updates, security, status]

--reverse, -r

Reverse the sort order (requires --sort) [Default: False]

save

Save the current inventory state to disk

inventory save

Manually save the current state of the inventory to disk using the configured cache file.

The data is compressed using LZMA.

If options.cache_autosave is enabled, this will be automatically invoked after every discovery or refresh operation.

Since this is enabled by default, you will rarely need to invoke this manually.

This command is only available in interactive mode, as the inventory state is not persisted between separate CLI invocations when autosave is disabled.

clear

Clear the inventory state and cache file (reset state)

inventory clear [OPTIONS]

This will empty the inventory cache file and re-initialize all hosts from scratch.

This is useful if you want to reset the inventory state, or have difficulties with stale data that cannot be resolved.

Note that this will remove all cached host data, so you will need to re-discover the entire inventory after this operation.

Parameters:

--force, -f

Do not prompt for confirmation [Default: False]

host

Host Operations Commands

Commands to query, refresh and discover individual hosts.

show is the primary command to display the current state of a host in the inventory.

show

Show detailed state of a specific host

host show [OPTIONS] HOST

This command retrieves the host by name from the inventory and displays its details in a rich format on the terminal.

Arguments:

HOST

Host from inventory to show [Required]

Parameters:

--updates, -u, --no-updates, -n

Show update details for the host [Default: True]

--security-only, -s

Show only security updates for the host when displaying updates [Default: False]

discover

Detect and gather platform data for a host

host discover HOST

This command retrieves the host by name from the inventory and synchronizes its platform data, such as OS, version and package manager.

Arguments:

HOST

Host from inventory to discover [Required]

refresh

Refresh the state and update data for a specific host

host refresh [OPTIONS] HOST

This command retrieves the host by name from the inventory and refreshes its state and available updates.

If --sync is specified, the package repositories will also be synchronized remotely.

Arguments:

HOST

Host from inventory to refresh [Required]

Parameters:

--sync, -s

Also sync package repositories [Default: False]

--discover, -d

Also refresh platform information [Default: False]

ping

Ping a specific host to check connectivity and online status

host ping HOST

The ping status is based on ssh connectivity, and will update the host's online status in the inventory accordingly.

Arguments:

HOST

Host from inventory to ping [Required]

connections

Connection State Management Commands

Commands to inspect the state of SSH connections to inventory hosts. These commands are only useful when SSH Pipelining is enabled, otherwise no persistent connections to hosts are maintained.

Only useful from Interactive Mode, as connections are not maintained between separate CLI invocations.

show

Show SSH connection state for inventory hosts

connections show [OPTIONS] [ARGS...]

Display the current SSH connection state for specified hosts, or all hosts if none are specified.

Connections that have been idle for longer than the configured maximum age will be marked as "Expiring".

Only useful when SSH Pipelining is enabled, and exclusively from interactive mode, as connections are not maintained between individual CLI invocations.

Arguments:

NAMES

Hosts to show connection state for. If omitted, shows all hosts.

Parameters:

--active, -a

Show only hosts with active connections. [Default: False]

close

Close SSH connections explicitly

connections close [OPTIONS] [ARGS...]

Close SSH connections to specified hosts, or all hosts if none are specified.

Only useful when SSH Pipelining is enabled, and exclusively from interactive mode, as connections are not maintained between individual CLI invocations.

Arguments:

NAMES

Hosts to close connections for. If omitted, close all connections.

Parameters:

--verbose, -v

Show detailed output of closed connections. [Default: False]

ui

Start the Exosphere User Interface

Launches the Text-based User Interface (TUI). When started from interactive mode, quitting the UI returns you to the prompt.

Takes no arguments; the 'start' subcommand is an alias kept for backward compatibility with older versions of Exosphere.

start

Start the UI (compatibility alias)

ui start

This subcommand is kept for backwards compatibility with older versions of Exosphere, to preserve the muscle memory of users who have relied on it since 1.0.0. It simply launches the UI, exactly like invoking 'ui' with no arguments.

configuration

Configuration-related Commands

Commands to inspect or modify the currently loaded configuration.

show

Show the current configuration

config show [OPTIONS] [ARGS]

Displays the current configuration options, or the value of a specific option if specified.

If --full is specified, it will show the entire configuration structure, including the inventory, beyond just the "options" section.

Arguments:

OPTION

Name of the option to show. All if not specified.

Parameters:

--full, -f

Show full configuration structure, including inventory. [Default: False]

source

Show the configuration source, where it was loaded from

config source [OPTIONS]

Displays the path of the configuration file loaded, if any, and any environment variables that affect the configuration.

Parameters:

--env, --no-env

Show environment variables that affect the configuration. [Default: True]

paths

Show the paths of application directories

config paths

Will display the platform-specific filesystem paths that exosphere uses for configuration, state, logs, and cache.

diff

Show the differences between the current configuration and the defaults

config diff [OPTIONS]

Exosphere follows convention over configuration, so your configuration file can exclusively contain the options you want to change.

This command allows you to see exactly what has been changed, optionally in its context, using the --full option.

For a full config dump, use the show command instead.

Parameters:

--full, -f

Show full configuration diff, including unmodified options. [Default: False]

edit

Open the current configuration file in an editor

config edit [OPTIONS]

Launches your text editor against the currently loaded configuration file. If no configuration file is loaded, the default platform path is opened instead, letting you create one from scratch.

The editor to use is determined from the editor configuration option and then falls back to the VISUAL and EDITOR environment variables, then finally, a platform default.

Changes do not affect the running process; they take effect on next startup. After editing, the file is validated and, if invalid, you are offered the chance to re-open the editor and fix it.

Parameters:

--validate, --no-validate

Validate the file after editing (default: enabled). [Default: True]

report

Reporting Commands

Commands to generate reports about the current state of the inventory. Allows exporting the state of the inventory to various formats, including JSON for use in other tools or custom reporting.

generate

Generate a report of the current inventory state

report generate [OPTIONS] [ARGS...]

The report can be generated in various formats, including html for for a pretty self-contained document, json for easy integration with other tools, or plain text for human readability.

The report can also be filtered to include only specific hosts by providing their names as arguments. If no hosts are specified, the report will include all hosts in the inventory.

It can further be narrowed to hosts with pending updates (--updates-only) or pending security updates (--security-updates-only), which are mutually exclusive.

Note: Undiscovered or unsupported hosts are excluded from the report.

Arguments:

HOSTS

One or more hosts to include (all if not specified)

Filtering Options:

--updates-only, -u

Only include hosts with available updates [Default: False]

--security-updates-only, -s

Only report security updates [Default: False]

Output Options:

--format, -f

Output format for the report [Choices: text, html, markdown, json, Default: text]

--output, -o

Write report to file (defaults to stdout)

--tee

Also print report to stdout (requires --output) [Default: False]

--quiet, -q

Suppress informational messages [Default: False]

--navigation, --no-navigation

Include navigation section (html only) [Default: True]

schema

Show or write the JSON Schema for the current version of Exosphere

report schema [ARGS]

Emits the JSON Schema (draft-07) describing the structure produced by report generate --format json, for the currently running version of Exosphere.

This allows anyone to easily get an overview of the structure, validate and integrate, offline, without a local source tree or access to the online documentation.

By default the schema is printed to stdout. Use --output to write it to a file instead.

Parameters:

OUTPUT, --output, -o

Write the schema to a file (defaults to stdout)

status

Show a brief, condensed status summary of the inventory.

report status

Prints a short, executive-summary overview of the whole inventory: how many hosts have pending updates (and how many of those include security updates), how many are awaiting a reboot, and whether any host data has gone stale.

The output is plain and compact, suitable as an at-a-glance overview or for inclusion in a system MOTD (e.g. by redirecting it to a file).

Color is automatically dropped when the output is not a terminal.

Hosts that have not yet been discovered contribute nothing to the update and reboot counts, as they have no known state.

sudo

Sudo Policy Management Commands

Exosphere providers may require sudo privileges to execute certain operations on remote systems. These commands allow you to inspect, validate and generate suitable sudoers configurations.

Exosphere has a global Sudo Policy that dictates how operations requiring those privileges are handled (the default is to skip them).

Individual hosts may override the global Sudo Policy with their own Sudo Policy in the inventory configuration.

For more details, see the Sudo Policies and Privileges section of the Exosphere documentation.

policy

Show the current global Sudo Policy

sudo policy

This command will display the current global Sudo Policy in effect. Individual hosts may override this with their own Sudo Policy.

check

Check the effective Sudo Policies for a given host

sudo check HOST

The command will take in consideration the current global Sudo Policy and the host-specific Sudo Policy (if defined) to determine if the host can execute all of its Package Manager provider operations.

Arguments:

HOST

Host to check security policies for [Required]

providers

Show Sudo Policy requirements for available providers

sudo providers [ARGS]

Some providers require sudo privileges to execute certain operations. You can use this command to enumerate these requirements, if applicable.

Arguments:

NAME

Provider to display. All if not specified.

generate

Generate a sudoers configuration for passwordless operations

sudo generate [OPTIONS]

Creates snippet suitable for /etc/sudoers.d/* on target systems.

Will use username from host configuration, global configuration, or current user if not specified.

Outputs to stdout, can be redirected to a file.

Parameters:

--user, -u

Override the username for the sudoers snippet

Target:

(Required, Mutually Exclusive)

--host, -h

Generate sudoers snippet based on host configuration

--provider, -p

Generate sudoers snippet for a specific provider

version

Version and Update Check Commands

Show current version, check for updates.

details

Show detailed version and environment information

version details

Displays the currently installed version along with Python version, virtual environment status, and operating system details.

check

Check for exosphere updates

version check [OPTIONS]

Compares the current installed version with the latest version available on PyPI and reports if an update is available.

Exits with code 3 if an update is available.

Parameters:

--verbose, -v

Show verbose output for check [Default: False]