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.
exosphere
Usage: exosphere [OPTIONS] COMMAND [ARGS]...
Exosphere CLI
The main command-line interface for Exosphere.
It provides a REPL interface for interactive use as a prompt, but can
also be used to run commands directly from the command line.
Run without arguments to start the interactive mode.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version -V Show version and exit │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to │
│ copy it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ inventory Inventory and Bulk Management Commands │
│ host Host Management Commands │
│ ui Exosphere User Interface │
│ config Configuration-related Commands │
│ report Reporting Commands │
│ sudo Sudo Policy Management │
│ version Version and Update Check Commands │
╰──────────────────────────────────────────────────────────────────────────────╯
inventory
Usage: exosphere inventory [OPTIONS] COMMAND [ARGS]...
Inventory and Bulk Management Commands
Commands to bulk query, discover and refresh hosts in the inventory.
Most commands acccept an optional list of host names to operate on.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ discover Gather platform information for hosts │
│ refresh Refresh the update data for all hosts │
│ ping Ping all hosts in the inventory │
│ status Show hosts and their status │
│ clear Clear the inventory state and cache file │
╰──────────────────────────────────────────────────────────────────────────────╯
discover
Usage: exosphere inventory discover [OPTIONS] [HOST]...
Gather platform information for hosts
On a fresh inventory start, this needs 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]... Host(s) to discover, all if not specified │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
refresh
Usage: exosphere inventory refresh [OPTIONS] [HOST]...
Refresh the update data for all hosts
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 synced.
Syncing 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]... Host(s) to refresh, all if not specified │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --discover -d Also refresh platform information │
│ --sync -s Sync the package repositories as well as updates │
│ --verbose -v Show verbose output during operations │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
ping
Usage: exosphere inventory ping [OPTIONS] [HOST]...
Ping all hosts in the inventory
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.
Invoke this to update the online status of hosts if
any have gone offline and exosphere refuses to run
an operation on them.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ names [HOST]... Host(s) to ping, all if not specified │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
status
Usage: exosphere inventory status [OPTIONS] [HOST]...
Show hosts and their status
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 only show hosts with pending
updates or security updates. Filtering for security updates
implies filtering for updates as well.
No matches when filtering will exit with code 3.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ names [HOST]... Host(s) to show status for, all if not specified │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --updates-only -u Show only hosts with pending updates │
│ --security-only -s Show only hosts with pending security updates │
│ (implies --updates-only) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
clear
Usage: exosphere inventory clear [OPTIONS]
Clear the inventory state and cache file
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.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --force -f Do not prompt for confirmation [required] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
host
Usage: exosphere host [OPTIONS] COMMAND [ARGS]...
Host Management Commands
Commands to query, refresh and discover individual hosts.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ show Show details of a specific host. │
│ discover Gather platform data for host. │
│ refresh Refresh the updates for a specific host. │
│ ping Ping a specific host to check its reachability. │
╰──────────────────────────────────────────────────────────────────────────────╯
show
Usage: exosphere host show [OPTIONS] NAME
Show details of a specific host.
This command retrieves the host by name from the inventory
and displays its details in a rich format.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Host from inventory to show [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --updates -u --no-updates -n Show update details for the host │
│ [default: updates] │
│ --security-only -s Show only security updates for the │
│ host when displaying updates │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
discover
Usage: exosphere host discover [OPTIONS] NAME
Gather platform data for host.
This command retrieves the host by name from the inventory
and synchronizes its platform data, such as OS, version and
package manager.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Host from inventory to discover [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
refresh
Usage: exosphere host refresh [OPTIONS] NAME
Refresh the updates for a specific host.
This command retrieves the host by name from the inventory
and refreshes its available updates.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Host from inventory to refresh [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --sync -s Also sync package repositories │
│ --discover -d Also refresh platform information │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
ping
Usage: exosphere host ping [OPTIONS] NAME
Ping a specific host to check its reachability.
This command will also update a host's online status
based on the ping result.
The ping status is based on ssh connectivity.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Host from inventory to ping [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
ui
Usage: exosphere ui [OPTIONS] COMMAND [ARGS]...
Exosphere User Interface
Commands to start the Text-based or Web-based User Interface.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ start Start the Exosphere UI. │
│ webstart Start the Exosphere Web UI. │
╰──────────────────────────────────────────────────────────────────────────────╯
start
Usage: exosphere ui start [OPTIONS]
Start the Exosphere UI.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
webstart
Usage: exosphere ui webstart [OPTIONS]
Start the Exosphere Web UI.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
config
Usage: exosphere config [OPTIONS] COMMAND [ARGS]...
Configuration-related Commands
Commands to inspect the currently loaded configuration.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ show Show the current configuration. │
│ source Show the configuration source, where it was loaded from. │
│ paths Show the paths of application directories. │
│ diff Show the differences between the current configuration and the │
│ defaults. │
╰──────────────────────────────────────────────────────────────────────────────╯
show
Usage: exosphere config show [OPTIONS] [OPTION]
Show the current configuration.
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 [OPTION] Name of the option to show. All if not specified. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --full -f Show full configuration structure, including inventory. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
source
Usage: exosphere config source [OPTIONS]
Show the configuration source, where it was loaded from.
Displays the path of the configuration file loaded, if any, and
any environment variables that affect the configuration.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --env --no-env Show environment variables that affect the │
│ configuration. │
│ [default: env] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
paths
Usage: exosphere config paths [OPTIONS]
Show the paths of application directories.
Will display the platform-specific filesystem paths that exosphere
uses for configuration, state, logs, and cache.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
diff
Usage: exosphere config diff [OPTIONS]
Show the differences between the current configuration and the defaults.
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.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --full -f Show full configuration diff, including unmodified │
│ options. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
report
Usage: exosphere report [OPTIONS] COMMAND [ARGS]...
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.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ generate Generate a report of the current inventory state. │
╰──────────────────────────────────────────────────────────────────────────────╯
generate
Usage: exosphere report generate [OPTIONS] [HOST]...
Generate a report of the current inventory state.
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.
Note: Undiscovered or unsupported hosts are excluded from the report.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ hosts [HOST]... One or more hosts to include (all if not specified) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --format -f [text|html|markd Output format │
│ own|json] for the report │
│ [default: text] │
│ --output -o FILE Write report to │
│ file (defaults │
│ to stdout) │
│ --updates-only -u Only include │
│ hosts with │
│ available │
│ updates │
│ --security-updat… -s Only report │
│ security updates │
│ --tee Also print │
│ report to stdout │
│ when using │
│ --output │
│ --quiet -q Suppress │
│ informational │
│ messages │
│ --navigation --no-navigation Include │
│ navigation │
│ section (html │
│ only) │
│ [default: │
│ navigation] │
│ --help Show this │
│ message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
sudo
Usage: exosphere sudo [OPTIONS] COMMAND [ARGS]...
Sudo Policy Management
Commands to view Sudo Policies, check resultant host policies,
list provider requirements, and generate sudoers snippets.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ policy Show the current global Sudo Policy. │
│ check Check the effective Sudo Policies for a given host. │
│ providers Show Sudo Policy requirements for available providers. │
│ generate Generate a sudoers configuration for passwordless operations. │
╰──────────────────────────────────────────────────────────────────────────────╯
policy
Usage: exosphere sudo policy [OPTIONS]
Show the current global Sudo Policy.
This command will display the current global Sudo Policy in effect.
Individual hosts may override this with their own Sudo Policy.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
check
Usage: exosphere sudo check [OPTIONS] HOST
Check the effective Sudo Policies for a given 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 TEXT Host to check security policies for [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
providers
Usage: exosphere sudo providers [OPTIONS] [NAME]
Show Sudo Policy requirements for available providers.
Some providers require sudo privileges to execute certain operations.
You can use this command to what they are, if applicable.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ name [NAME] Provider to display. All if not specified. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
generate
Usage: exosphere sudo generate [OPTIONS]
Generate a sudoers configuration for passwordless operations.
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.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Mandatory Options (mutually exclusive) ─────────────────────────────────────╮
│ --host -h TEXT Generate sudoers snippet based on host │
│ configuration │
│ --provider -p TEXT Generate sudoers snippet for a specific provider │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Optional ───────────────────────────────────────────────────────────────────╮
│ --user -u TEXT Override the username for the sudoers snippet │
│ [default: (Host username OR default username OR │
│ Current user, in that order)] │
╰──────────────────────────────────────────────────────────────────────────────╯
version
Usage: exosphere version [OPTIONS] COMMAND [ARGS]...
Version and Update Check Commands
Show current version, check for updates.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ details Show detailed version and environment information │
│ check Check for exosphere updates │
╰──────────────────────────────────────────────────────────────────────────────╯
details
Usage: exosphere version details [OPTIONS]
Show detailed version and environment information
Displays the currently installed version along with Python version,
virtual environment status, and operating system details.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
check
Usage: exosphere version check [OPTIONS]
Check for exosphere updates
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.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --verbose -v Show verbose output for check │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯