Web TUI

The web command is a terminal UI that puts browser chrome — a URL bar, navigation, and modes — inside a terminal pane. It connects to the GUI (Ghostboard), which renders the actual web page as an overlay using a browser engine (Roamium). You drive the browser from the keyboard without leaving the terminal.

web example.com

The browser appears inline. You start in Control mode; press Enter to switch to Browse mode and interact with the page, and Esc to return to Control.

Command line

Usage is web [URL] [options], with optional subcommands:

Subcommand	Action
`web url <url>`	Open a URL in the browser pane
`web file <path>`	Open a local file in the browser pane
`web last`	Print the last active browser pane/tab
`web status`	Print the Chromium tab inventory for the current profile

Options (valid with any subcommand):

Option	Meaning
`-p`, `—profile <name>`	Browser profile to use (default `default`)
`—incognito`	Use an ephemeral private profile
`-b`, `—browser <name\|path>`	Browser binary — a name or an absolute path
`—primary-screen`	Render in the primary terminal screen instead of the alternate screen

Profile names must be lowercase alphanumeric and start with a letter. —incognito cannot be combined with —profile unless the profile is incognito. Each profile keeps its own cookies, storage, and cache (see the configuration guide for where profiles are stored). The —browser flag is mainly for development — pass an absolute path to test a specific engine build:

web —browser /path/to/roamium example.com

URL resolution

Whatever you type — as an argument or in the URL bar — is resolved to a URL by these rules, in order:

Already has a scheme (https://…, file://…) — used as-is.
Starts with /, ./, or ../ and the file exists — opened as file://.
Contains : — treated as host:port (http:// for localhost, otherwise https://).
Names an existing file — opened as file://.
Looks like a domain (contains a dot) — https:// (localhost gets http://).
Otherwise it isn’t treated as a URL or file: nothing is navigated and an error is shown (in the command bar when editing, or on stderr from the CLI).

You type	You get
`example.com`	`https://example.com`
`localhost:3000`	`http://localhost:3000`
`./page.html`	`file://…/page.html`

Modes

The TUI has six modes:

Mode	Behavior
Control	Default. TUI keybindings active.
Browse	Keyboard and mouse go to the page.
Edit	Vim-style URL editing (Normal / Insert / Visual / Search submodes).
Command	Command entry prefixed with `:`.
Dialog	Answering a JavaScript dialog (alert / confirm / prompt / beforeunload).
Auth	Entering HTTP authentication credentials.

Keybindings

Control mode

Key	Action
`Enter`	Switch to Browse mode
`i`	Edit the URL (insert at cursor)
`A`	Edit the URL (insert at end)
`I`	Edit the URL (insert at start)
`n`	Edit the URL (Normal submode)
`v`	Edit the URL (Visual submode)
`V`	Edit the URL (Visual line select)
`:`	Enter Command mode
`Cmd+C`	Copy the current URL

The URL-edit keys and Cmd+C are disabled when the pane is a DevTools split.

Browse mode

Key	Action
`Esc`	Return to Control mode

Every other key (and the mouse) goes straight to the page, so standard browser shortcuts like Cmd+[ / Cmd+] (back / forward) and Cmd+R (reload) work because Chromium handles them — they are not TUI bindings.

Edit mode

Key	Action
`Enter`	Resolve and navigate to the URL, then switch to Browse mode
`Esc`	From the Normal submode, return to Control mode

The URL editor uses vim-style editing (h/l, w/b, x, d, y, p, …) with system-clipboard integration. Enter does not navigate from the Search submode or in a DevTools split.

Command mode

Type a command (see below) and press Enter to run it; Esc from the Normal submode returns to Control mode.

Dialog mode

When a page opens a JavaScript dialog, Enter accepts it (and submits the typed text for a prompt) and Esc cancels; for confirm / beforeunload, y and n also work.

Auth mode

For an HTTP authentication challenge, Tab switches between the username and password fields, typing fills the active field, Enter advances from username to password and then submits, and Esc cancels.

Any mode

Key	Action
`Ctrl+C`	Quit

Commands

Enter Command mode with :. Commands match by exact name or alias.

Command	Alias	Action
`:quit`	`:q`	Quit
`:dark [on\|off\|system]`	`:da`	Force page dark mode on, off, or follow the system; no argument toggles
`:viewport height <rows>`	`:vp`	Set the browser viewport height in terminal rows
`:viewport reset`	`:vp r`	Reset the viewport height
`:devtools [right\|down\|left\|up]`	`:de`	Open DevTools in a split pane (default `right`)

:dark also accepts yes/y and no/n for on/off, and s for system. :devtools direction shortcuts are r, d, l, u.

DevTools and dark mode

:devtools opens Chromium DevTools for the current tab in an adjacent split. The URL-edit and copy keys are disabled in a DevTools pane, and it does not navigate. :dark forwards a preferred color scheme to the page (independent of the terminal theme set in your config).

How the TUI, the GUI, and the engine processes fit together — and how browser content is composited into the terminal — is covered in Architecture. For terminal-level key bindings (a separate system from the TUI modes above), see Keybindings.