🖥️ Nucleus CLI Documentation

Nucleus is the command-line interface (CLI) for installing, configuring, and managing AtomOS and its services. It supports installation, updates, service management, vault creation, network bridge setup, module installation, and developer utilities for AtomOS environments on AlmaLinux, Ubuntu, and Debian systems.

Requirements

Root privileges are required for most operations.
Supported distros: AlmaLinux, RockyLinux, Ubuntu, Debian.
Minimum: 2 CPU cores, 2GB RAM.
Internet access for installation and updates.

Installation of Nucleus CLI

The recommended way to install the Nucleus CLI is to use the provided get-atomos.sh script:

curl -fsSL https://repo.elemento.cloud/get-atomos.sh | sudo bash

This will download the latest nucleus CLI to /usr/bin/nucleus, make it executable, and set up a monthly cron job to check for updates. After installation, you can use the nucleus command from anywhere in your shell.

If you want to use a local copy for development or testing, you can still run ./nucleus.sh directly.

Usage

sudo nucleus [OPTIONS]

or (for local development):

sudo ./nucleus.sh [OPTIONS]

Main Options

Installation & Update

-i, --install PACKAGE TYPE Install AtomOS (PACKAGE: Compute, Storage, Full; TYPE: on-prem, cloud)
-u, --update Update AtomOS services
-c, --check Check if AtomOS is installed
-v, --version Show current AtomOS version
-I, --info Show host and AtomOS info (also checks requirements)
-vs, --verify-install Verify correct installation of AtomOS
-U, --uninstall Uninstall AtomOS (requires confirmation)

Logs & License

-rl, --logs Show installation logs
-l, --license Check license file

Vault Utilities

--vault-creator Vault creator utility (setup and manage vaults)
--volume-info List vault/volume settings

Service Management

-s, --status Check if all services are up and running
-j, --journal SERVICE [TIME] Show logs of a service (optionally since TIME)
-r, --reset Reset Storage service
-hr, --hard-restart Hard restart all AtomOS services (requires confirmation)
--start SERVICE Start an AtomOS service
--stop SERVICE Stop an AtomOS service
--restart SERVICE Restart an AtomOS service
-R, --run SERVICE Run an AtomOS service in terminal
-sa, --start-all Start all AtomOS services
-ra, --restart-all Restart all AtomOS services
-ta, --stop-all Stop all AtomOS serviecs

Network Bridge Setup

Bridge setup is performed automatically during installation. You can also run it manually:
```
sudo nucleus --bridge-setup
```
This will prompt for network interface selection and create a bridge using nmcli. If a bridge named br0 already exists, you will be prompted to choose a different name.

Module Installation

After AtomOS installation, you will be prompted to select and install extra modules from the official repository.

Other

-dr, --dry-run Dry-run commands
--checkupdate Check for Nucleus updates
-h, --help Show help message

Example Installation

Install AtomOS (RHEL/AlmaLinux):

sudo nucleus --install compute on-prem
sudo nucleus --install storage cloud
sudo nucleus --install full on-prem

Install AtomOS (Ubuntu/Debian):
```
sudo nucleus --install storage on-prem
```
Compute/Full packages are not available for Ubuntu/Debian.

Service Management Examples

Check status:
```
sudo nucleus --status
```

Start/Stop/Restart a service:

sudo nucleus --start matcher
sudo nucleus --stop storage
sudo nucleus --restart network

Run a service in terminal:
```
sudo nucleus --run matcher
```

Show service logs:

sudo nucleus --journal matcher "2025-07-21 10:00:00"
sudo nucleus -j storage --live

Vault Utilities Example

AtomOS storage can manage VM volumes on certain positions, we call those: vaults.

Create or manage vaults:
```
sudo nucleus --vault-creator
```
This utility helps set up the default Elemento vault and create custom vaults with specific settings.
Print vault/volume infos:
```
sudo nucleus --volume-info
```

CLI Usage Examples

Below are examples for all main Nucleus CLI commands and options:

Installation & Update

Install AtomOS (Compute, Storage, or Full):

sudo nucleus --install compute on-prem
sudo nucleus --install storage cloud
sudo nucleus --install full on-prem

Update AtomOS:
```
sudo nucleus --update
```
Check if AtomOS is installed:
```
sudo nucleus --check
```
Show current AtomOS version:
```
sudo nucleus --version
```
Show host and AtomOS info (system requirements, versions, distro):
```
sudo nucleus --info
```
Uninstall AtomOS (requires confirmation):
```
sudo nucleus --uninstall --force
```

Logs & License

Show installation logs:
```
sudo nucleus --logs
```
Check license file:
```
sudo nucleus --license
```

Vault Utilities

Create or manage vaults:
```
sudo nucleus --vault-creator
```

Service Management

Check status of all services:
```
sudo nucleus --status
```

Show logs of a service (optionally since a specific time):

sudo nucleus --journal matcher
sudo nucleus --journal matcher "2025-07-21 10:00:00"

Reset Storage service:
```
sudo nucleus --reset
```
Hard restart all AtomOS services (requires confirmation):
```
sudo nucleus --hard-restart
```

Start/Stop/Restart a service (requires confirmation):

sudo nucleus --start matcher
sudo nucleus --stop storage
sudo nucleus --restart network

Run a service in terminal:
```
sudo nucleus --run matcher
```

Network Bridge Setup

Manually set up a network bridge:
```
sudo nucleus --bridge-setup
```

Module Installation

Nucleus can help you to install and manage our favourites tools.

After AtomOS installation, you will be prompted to select and install extra modules from the official repository. To repeat this step:
```
sudo nucleus --modules
```

In this moment we give the modules for:

ZFS
GlusterFS
BTRFS (beta) [only on Alma]

Those modules follows the official guidelines of the mantainers, we wrapped them in simple and automatic script to simplify the installation for the end user.

Other

Check for Nucleus updates:
```
sudo nucleus --checkupdate
```
Show help message:
```
sudo nucleus --help
```

Notes

Most commands require root privileges.
Use --force for invasive actions (uninstall, hard-restart, start/stop/restart services).
For more information, visit https://elemento.cloud