boxctl — Command Reference¶

boxctl-clock - Control fake hardware clock

    Usage:
      ${FRAMEWORK_SCRIPT_NAME:-${0}} [load|save] [-h|--help]

    Background
        Many embedded Linux systems do not have a functional hardware clock.
        Either they simply don't have a hardware clock at all
        or they have a hardware clock but it is not usable
        (e.g. because Linux doesn't know how to use it or because no battery is present).

        This can lead to time moving backwards
        to some default value (often 1970) when the system is rebooted.

        Since lots of software assumes that time only moves forward this is a bad thing.
        NTP can (and should where practical) be used to sync with an external timeserver
        but it is not available early in the boot process and may be unavailable for other reasons.

        The design expectation of boxctl clock
        is that it will be run very late at shutdowna and very early at boot.
        This will ensure that fsck has a vaguely sensible idea of system time
        at boot and won't complain that the last-modified time in the filesystem
        is not hugely in the past or future.

        Some users may not worry about this too use case,
        in which case it is possible to modify the init system configuration
        to move things earlier/later as appropriate.

    Example:
      ${FRAMEWORK_SCRIPT_NAME:-${0}} save
      ${FRAMEWORK_SCRIPT_NAME:-${0}} load

Usage: boxctl confext <command>

Manage configuration extension images in /data/extensions/confext/.

Commands:
  list      List installed extensions and their merge status
  merge     Merge all extensions into /etc/
  unmerge   Remove merged extensions from /etc/
  refresh   Unmerge then re-merge (picks up new or removed images)
  status    Show current merge state

Extensions are .raw squashfs images stored in /data/extensions/confext/.
Drop files there and run 'boxctl confext refresh' to apply them.

Usage: boxctl config <subcommand> [args]

Subcommands:
  get <key>           Read a config value
  set <key> <value>   Write a config value
  list                List all config keys
  apply               Apply hostname and timezone from config

Keys (common):
  hostname            Device hostname
  timezone            TZ name (e.g. Europe/Amsterdam)

Usage: boxctl diagnose [--output <dir>]

Collect diagnostics and write a tarball to /tmp (or <dir>).

Collects:
  - RAUC slot status
  - Failed systemd units + their journals
  - AppArmor denials (dmesg)
  - Last boot log
  - Current boot log
  - WiFi status
  - Disk and memory usage

Options:
  --output <dir>   Write tarball to this directory (default: /tmp)

Usage: boxctl firewall <command>

Manage the nftables firewall.

Commands:
  list      Show the current ruleset (nft list ruleset)
  reload    Reload static rules and per-app fragments
  reset     Flush all rules and remove firewall state
  up        Load rules (same as reload; used after down)
  down      Flush all rules and mark firewall inactive

Usage: boxctl logs [options]

Options:
  -u, --unit <unit>     Filter by systemd unit
  -p, --priority <p>    Min priority: emerg|alert|crit|err|warning|notice|info|debug
  -n, --lines <n>       Number of lines (default: 50)
  -f, --follow          Follow live output
  --boot                Show current boot only

Usage: boxctl net <subcommand> [args]

Subcommands:
  status                Show current WiFi state and IP
  scan                  Scan for available networks
  connect <ssid> <psk>  Connect to a WiFi network

Usage: boxctl power [<subcommand>]

Manage runtime power profile (cpufreq governor + USB autosuspend).

Subcommands:
  get           Show the active profile (default)
  set <name>    Persist and apply a profile
  apply         Re-apply the persisted profile — called at boot by power-profile.service
  list          List available profiles

Profiles:
  performance   CPU governor: performance, USB autosuspend: disabled
  balanced      CPU governor: schedutil,   USB autosuspend: 2000ms  (default)
  saver         CPU governor: powersave,   USB autosuspend: 500ms

Usage: boxctl reboot [<slot>]

Reboot the device, optionally into a specific RAUC slot.
If no slot is given, performs a normal reboot.

Arguments:
  <slot>   RAUC slot name (e.g. rootfs.0, rootfs.1)

Usage: boxctl rollback

Roll back to the previously installed RAUC slot.

Finds the inactive rootfs slot, marks it as the boot target, and offers
to reboot. The current slot is not modified — you can roll forward again
by running: boxctl update

Usage: boxctl screen <subcommand> [args]

Manage HDMI display configuration. Settings are stored in /data/config and
written to /boot/firmware/config.txt on apply. A reboot is required for
changes to take effect.

Subcommands:
  status                     Show stored screen configuration
  rotate <degrees>           Set display rotation: 0, 90, 180, 270
  resolution <group> <mode>  Set HDMI resolution (hdmi_group and hdmi_mode)
  apply                      Write stored settings to /boot/firmware/config.txt

Common HDMI groups and modes:
  Group 1 (CEA/TV):  mode 4 = 720p60,  mode 16 = 1080p60
  Group 2 (DMT/PC):  mode 35 = 1024x768@60, mode 82 = 1920x1080@60

Usage: boxctl service <subcommand> [service]

Subcommands:
  list                List attached portable services and their state
  start <service>     Start a portable service
  stop <service>      Stop a portable service
  enable <service>    Enable a portable service (start on boot)
  disable <service>   Disable a portable service

Usage: boxctl status

Show system health: RAUC slot info, AppArmor, dm-verity, failed units,
disk and memory usage.

Usage: boxctl sysext <command>

Manage system extension images in /data/extensions/sysext/.

Commands:
  list      List installed extensions and their merge status
  merge     Merge all extensions into /usr/
  unmerge   Remove merged extensions from /usr/
  refresh   Unmerge then re-merge (picks up new or removed images)
  status    Show current merge state

Extensions are .raw squashfs images stored in /data/extensions/sysext/.
Drop files there and run 'boxctl sysext refresh' to apply them.

Browse utils in framework

    This script prints a nice overview
    of all framework scripts using fzf with preview.

    ${FRAMEWORK_SCRIPT_NAME:-${0}} [-h|--help]

    Arguments:
      -d, --directory - The directory to list tools for
      -h, --help      - Show this menu

    Example:
      ${FRAMEWORK_SCRIPT_NAME:-${0}}

Usage: boxctl update [<bundle>]

Apply a RAUC bundle. If no path is given, searches /mnt for *.raucb files.
Prompts for confirmation before installing.

Arguments:
  <bundle>   Path to a .raucb file (optional — scans /mnt if omitted)