> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryoku.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert an existing Arch machine

> Turn an existing Arch install into a Ryoku machine with one reversible command.

Already running Arch? You do not need the ISO. One command converts your machine
into a Ryoku box in place — and the same tool undoes it. Everything it touches is
backed up first, your desktops and files stay put, and Ryoku is layered on top
rather than installed over you.

<Info>
  Starting from a clean disk or a new machine instead? Boot the signed ISO — see
  [Install Ryoku](/docs/install).
</Info>

## The one-liner

Run this as your **normal user** — not root. The script calls `sudo` only when it
actually needs elevation.

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/neur0map/ryoku-arch/main/ryoku-shell-installer/install.sh | bash
```

`install.sh` is a deliberately dumb bootstrap: it checks the machine is Arch-based
and `x86_64`, downloads the `ryoku-shell-install` binary, SHA256-verifies it
against a committed checksum, and hands it your terminal. Every real decision
lives in that interactive installer. Curious about the verification path first?
See [Verifying downloads](/docs/security).

### Flags and options

To convert interactively, just pipe the script to `bash`. To pass options through
to the installer, add them after `bash -s --`:

| Flag          | What it does                                                   |
| ------------- | -------------------------------------------------------------- |
| `--dry-run`   | Print every command it *would* run and change nothing.         |
| `--yes`       | Headless: run the default plan with no prompts.                |
| `--uninstall` | Reverse a previous conversion (see [Reversible](#reversible)). |

For example, a full dry run that touches nothing:

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/neur0map/ryoku-arch/main/ryoku-shell-installer/install.sh \
  | bash -s -- --dry-run
```

To fetch the installer and its config payload from a specific git ref instead of
`main`, set `RYOKU_SHELL_REF`:

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/neur0map/ryoku-arch/main/ryoku-shell-installer/install.sh \
  | RYOKU_SHELL_REF=<ref> bash
```

<Warning>
  Non-systemd systems (Artix and friends) are refused. On Manjaro the installer
  demands a typed acknowledgement and refuses `--yes` unless `RYOKU_ALLOW_MANJARO=1`
  is set — the `[ryoku]` repo tracks Arch current, which Manjaro stable trails. With
  Secure Boot enforcing, the NVIDIA toggle is forced off and locked (Arch kernels
  reject unsigned DKMS modules); sign with `sbctl` or disable Secure Boot, then
  re-run.
</Warning>

## What it does

The installer is a TUI that shares the ISO installer's visual language. It works
in three acts — scan, review, install — and writes nothing until you confirm.

<Steps>
  <Step title="Verify prerequisites">
    Confirms an Arch-based system (`pacman` present), `x86_64`, `curl`, and a
    non-root user, then downloads the `ryoku-shell-install` binary and
    SHA256-verifies it against its committed checksum before running it.
  </Step>

  <Step title="Scan your machine">
    Detects your GPU and Secure Boot state, the display manager and network
    stack, installed desktops (GNOME/KDE/Cinnamon/Xfce), rival Quickshell shells
    (Noctalia, DankMaterialShell, Caelestia, iNiR), known Hyprland rices (ML4W,
    HyDE, JaKooLit, end-4), conflicting user daemons (dunst, mako, waybar, swww),
    any plain Hyprland/niri/sway to migrate from, an Omarchy install to retire,
    your keyboard layout and btrfs — plus an interrupted previous run to resume.
  </Step>

  <Step title="Review the plan">
    Every decision is a toggle you approve before anything runs: NVIDIA
    proprietary drivers, switch the login screen to SDDM, point it at the Ryoku
    greeter, switch to NetworkManager, remove rival shells, disable conflicting
    daemons, retire an Omarchy repo, carry over your monitor and keyboard layout,
    AUR extras, a developer toolchain, and fish as your login shell. Nothing is
    forced; the list groups under section headers once it gets long.
  </Step>

  <Step title="Back up everything it will touch">
    Before the first change, every config the plan touches is copied to
    `~/.local/state/ryoku/shell-install/backup-<timestamp>/`, alongside a
    generated `restore.sh`. That script grows a line per saved item, so a kill at
    any moment still leaves a script that undoes exactly what happened so far.
  </Step>

  <Step title="Add the [ryoku] repo and install">
    Retires any legacy repo, runs `pacman -Syu`, clones the config payload,
    trusts the `[ryoku]` repository and keyring, removes anything you toggled,
    installs the Ryoku desktop packages and your GPU drivers, then wires up
    SDDM, the greeter, and NetworkManager.
  </Step>

  <Step title="Materialize and self-check">
    Runs `ryoku materialize` to lay down your `~/.config` (salvaging your monitor
    and keyboard layout from the old setup), installs any AUR extras, then runs
    `ryoku doctor` and verifies. Interrupted? Re-run — completed steps are
    recorded in `~/.local/state/ryoku/shell-install-state.json`, so it resumes
    from where it stopped and continues the same backup.
  </Step>
</Steps>

When it finishes, reboot to land in the Ryoku greeter and your new session. From
there it is an ordinary Ryoku box: `ryoku update` keeps it current and
`ryoku doctor` heals it. Continue with [First boot](/docs/first-boot) for the
first keys worth pressing.

## Reversible

The conversion is fully undoable. The reliable way to reverse it is to re-run the
one-liner with `--uninstall`:

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/neur0map/ryoku-arch/main/ryoku-shell-installer/install.sh \
  | bash -s -- --uninstall
```

<Note>
  If the `ryoku-shell-install` binary is still on your `PATH`, `ryoku-shell-install --uninstall`
  does the same thing. The bootstrap above always works because it re-fetches the
  installer for you.
</Note>

Uninstall walks the exact inverse of the conversion:

1. Removes the Ryoku packages in one `pacman -R` transaction (`ryoku-desktop`
   depends on the rest, so pacman orders the removal itself).
2. Drops the `[ryoku]` stanza from `/etc/pacman.conf`, keeping the original
   beside it.
3. Walks the backup chain **newest to oldest**, running each `restore.sh` with a
   confirmation prompt — putting every saved config back and re-enabling the
   services and display manager that run disabled. (Decline one and the walk
   stops there: the chain only makes sense in order.)

Session packages (SDDM, PipeWire, NetworkManager, …) are left installed — they
may predate Ryoku, and removing them can lock you out of a login. Your backup
directories are kept too; delete them once you are sure.

<Tip>
  To roll back only the most recent conversion rather than the whole chain, run
  that run's own restore script directly:
  `bash ~/.local/state/ryoku/shell-install/backup-<timestamp>/restore.sh`.
</Tip>

## What is touched vs left alone

The conversion is additive by design. It layers Ryoku on top of your system and
records how to peel it back off.

| Left alone                                                                                                 | Migrated or changed (only with your toggle)                                   |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Desktop environments (GNOME, KDE, Cinnamon, Xfce) — never uninstalled, stay selectable at the login screen | Rival Quickshell shells — uninstalled, but only if you toggle it              |
| niri and sway — kept installed as fallback sessions                                                        | Conflicting daemons (dunst, mako, waybar, swww) — disabled, never uninstalled |
| Your files and personal data                                                                               | The old display manager — disabled (not removed) in favour of SDDM            |
| Session packages on uninstall (SDDM, PipeWire, NetworkManager)                                             | The `[ryoku]` repo and keyring — added, then dropped again on uninstall       |

Every config the installer touches is **copied, never deleted** — originals for
system files are kept as `*.pre-ryoku`, and per-run copies live in the backup
directory with their `restore.sh`. Your monitor layout and keyboard intent are
salvaged from your existing setup (Hyprland first, then niri, sway, KDE, GNOME,
finally `localectl`) so your screens and keys come back the way you had them.

## Next steps

<CardGroup cols={2}>
  <Card title="Install from the ISO" icon="download" href="/docs/install">
    Prefer a clean disk? Boot and install the signed Ryoku ISO instead.
  </Card>

  <Card title="First boot" icon="power" href="/docs/first-boot">
    What you see after login, and the first keys worth pressing.
  </Card>
</CardGroup>