# 6. The console

`alloy` is the one program Alloy authors. It is a set of terminal views over
the CLIs that already run the system, sharing one palette, one keymap, and one
habit: every action shows the command it ran.

That last part is the point. The console is not a layer over the system you
have to learn instead of the system. It shows you `nmcli connection up 'Coffee
Shop Wifi'` in a pane at the bottom of the screen, and the day you want to
script that, you already know what to type.

## The verbs

| Command | What it shows |
|---|---|
| `alloy net` | Interfaces, connections, the wifi radio |
| `alloy audio` | Streams, outputs and inputs, and which is routed where |
| `alloy bluetooth` | Devices, and what state each one is actually in |
| `alloy display` | Outputs sway is driving: scale, rotation, on or off |
| `alloy mesh` | Mesh VPN peers, exit node, admin console (alias: `alloy tail`) |
| `alloy sync` | Synchronized folders, devices, and pending invitations |
| `alloy pkg` | What is installed and where it lives |
| `alloy disk` | Attached storage: mount, unmount, eject |
| `alloy update` | The booted image, the staged one, and rollback |
| `alloy settings` | System settings and application configs |
| `alloy config <path>` | One config file, opened directly |
| `alloy setup` | The first-boot enrollment offer |
| `alloy install` | The installer |
| `alloy theme apply` | Put the day or night skeleton in place |
| `alloy status --bar` | The status line, as JSON. Run by the bar, not by you |

`alloy --help` lists them, and `alloy <verb> --help` covers the flags.

## Settings

`alloy settings` is two tabs over one form.

**System** holds live state: timezone, network time, hostname, locale, keymap,
and the theme. Rows here commit as you edit them, because setting a timezone is
atomic on its own. Each writing row runs exactly one command, and each of those
is narrowly granted so it does not prompt for a password.

That grant is for the session sitting at the machine. Over ssh the same rows do
prompt, and the console tears its screen down so polkit can ask in the terminal,
then comes back where you were.

The clock is shown and never settable. Moving a system clock invalidates
certificates and reorders logs; the row is there so you can see what changing
the timezone did.

**Applications** holds config files, listed by the app they configure rather
than by path. You pick `shop`, not `~/.config/shop/config.toml`. Editing here is
schema-driven: fields carry types, ranges, allowed values, and their own help
text, and the file keeps its comments and key order when it is written back.

File-backed forms save with `Ctrl+S`. Live-state rows have nothing to save.

Not every config gets a form. sway's is neither TOML nor KDL, so it opens as
plain text instead: syntax-highlighted, with line numbers, saved with the same
`Ctrl+S`. It is in the list for the same reason everything else is, because
"where do I configure sway" should have an answer.

The text pane is a fallback and not an editor. There is no undo and no search;
the machine ships `helix` for that. Press Enter to start typing in it and Esc to
stop, which keeps what you typed rather than throwing it away. A config the
console could not parse opens the same way, with the parse error above it, so a
file that is broken is still a file you can fix here.

`alloy config <path>` opens one file's form directly, with no tabs and no app
list. The path has to be one a schema names as its target; anything else is
refused rather than opened as an empty form.

## A row that says it cannot do something

If a row is shown but not settable, and says why, that is deliberate. A tool
that did not answer, or a vocabulary that came back empty, gets reported rather
than hidden: hiding it would answer "where do I set this" with silence, and
offering it would promise a command that is not there.

## What the console will not do

- **It does not browse or search a catalog.** `alloy pkg` shows what is
  installed, where it lives, and what each surface costs. It will not help you
  find software you have not named.
- **It is not a systemd control panel.** `systemctl` is fine.
- **It is not a launcher or a shell.** You invoke it for a task and close it.

## Not built yet

- `alloy theme <name>` for swapping the runtime theme without logging out.
  Today the theme is chosen in `alloy settings` and applied at the next login.
- MagicDNS lookup and share/unshare in `alloy mesh`.
- Multi-output mode picking in `alloy display`. Scale and enable work; the mode
  picker waits on a machine with two displays to test against.