Skip to content
AerynOS Docs

Manage Moss States and Packages

Moss keeps track of packaging-related operations that change the state of the /usr directory by creating a new filesystem transaction (fstx) for each associated moss operation, be it package installation, removal or upgrades.

Use the commands below to inspect and manage those states, discover software, and keep your system current.

Check the current state

  1. List the active state to confirm what is running right now.
Terminal window
moss state active
  1. Review the state history when you need context for a rollback.
Terminal window
moss state list

Use the state ID (the number after State #) when you need to query or activate a specific snapshot.

Activate a different state

Follow these steps to roll back or advance to another state safely.

  1. Identify the target state ID with moss state list.
  2. Activate that state.
Terminal window
sudo moss state activate 128
  1. Verify the change.
Terminal window
moss state active

Activating a state atomically swaps the currently active state’s /usr directory with the new states’s /usr directory, using the Linux kernel renameat2 syscall.

On successful activation of the new state, it is recommended to reboot the system, so that long-running services start with the expected binaries, libraries, and configurations.

Search for packages

Use keyword searches to discover software by name or summary.

Terminal window
sudo moss search fractional

Add --installed (-i) if you only want to search software that is already present on the system.

Search for installed files

Look up which package delivered a specific file when you troubleshoot or audit an installation.

Terminal window
sudo moss search-file libEGL.so

moss search-file scans files from installed packages only.

Install software

  1. Refresh repository metadata when needed.
Terminal window
sudo moss repo update
  1. Install one or more packages.
Terminal window
sudo moss install howdy-git

Moss creates a new state automatically. Confirm success with moss state active.

Update the system

Keep the entire system current with a sync operation.

Terminal window
sudo moss sync --update

--update (-u) pulls fresh repository metadata before applying upgrades. Moss records the result as a new state, so you can roll back if something goes wrong.

Remove software

Uninstall packages you no longer need.

Terminal window
sudo moss remove howdy-git

Moss snapshots the removal in a new state. Use moss state list to find the previous state if you have to recover.

List currently installed software

Terminal window
moss list installed