Going places and keys¶

This page covers keywords, the command line, the two key presets, keys of your own, and keys that work on one site only. It ends with every action and its keys.

Keywords¶

A keyword is a short word for a site: gh rs-rich in the address bar, or noctiluca gh rs-rich on the command line, searches GitHub for rs-rich. The words after the keyword fill in the keyword's template, escaped. A keyword alone opens its site's home.

Typed	Keyword result

Four are built in:

Add your own, or change or remove a built-in, under [shortcuts]:

[shortcuts]
# {} takes the words after the keyword; the home is the template's site.
so = "https://stackoverflow.com/search?q={}"
# A table sets the search and the home apart.
wiki = { search = "https://en.wikipedia.org/w/index.php?search={}", home = "https://en.wikipedia.org" }
# No {}: the keyword opens this address, words or not.
news = "https://lobste.rs"
# false removes a built-in.
mdn = false

A site's own keyword. In a site's table, keyword = "s" makes s WORDS search the site you are on: the words go to your search engine with site:HOST in front. A bookmark's keyword works like a shortcut too (see Bookmarks).

When several could match, the address bar tries an address first, then this site's keyword, then a bookmark's, then [shortcuts], and searches last. See the address bar.

The command line¶

noctiluca [OPTIONS] [URL | FILE | KEYWORD WORDS…]
noctiluca keys [--site HOST] [--config PATH]
noctiluca ls [--json]
noctiluca action [--session PID] [--json] [--no-wait] VERB [ARGS…]

A switch that takes a value takes it as the next word or after = (--images=kitty). An unknown switch is an error, with the usage.

--dump is for scripts and CI. It opens the page, waits until it has loaded and stayed still for a moment (up to a minute), prints, and exits:

• text: the page's text, block by block;
• ax: one line per control, tab-separated: its role, its name, then value=…, checked, unchecked or mixed, disabled and its link, where they apply;
• json: the address, the title, the blocks, the controls and the media, with their positions.

noctiluca ls and noctiluca action list and drive the sessions started with --control: see Scripts and coding agents.

noctiluca keys prints every action with its keys, after your config, and then your site keys. noctiluca keys --site github.com prints only the keys of the site tables that match that host.

The mouse¶

Noctiluca takes the mouse while it runs full-screen:

A click on plain text does nothing, so a drag over text selects it and copies it to the clipboard. Most terminals also select with Shift held while an app has the mouse. --no-mouse leaves the mouse to the terminal altogether. Clicks land on whole cells.

The key presets¶

Two sets of keys come with Noctiluca. [keys] preset in the config chooses one:

• vim (the default): the keys of vim-like browsers. o opens, f shows hints, / finds, H and L go back and forward.
• plain: arrows and modifiers. Ctrl+O opens, Alt+H shows hints, Ctrl+F finds, Alt+Left and Alt+Right go back and forward.

Both are in the table below.

Your own keys¶

Rebind any action by its id under [keys]. Keys separated by spaces (or commas) are alternatives:

[keys]
preset = "vim"
hints = "f ctrl+g"        # f or Ctrl+G shows hints
reader = "ctrl+r"
quit = "none"             # none (or "") unbinds an action

Key names are like ctrl+g, alt+left, shift+f3, f6, pagedown, space, and a letter by itself (G is Shift+G). A rebound key leaves the action it used to run. The F1 overlay and noctiluca keys show the keys in effect.

A line that names no action, or has a key name Noctiluca does not know, is a warning: that line is skipped, its action keeps the preset's keys, and every other line still applies. The warnings show on the status line when Noctiluca starts, and noctiluca keys prints them all.

Keys on one site¶

A key can do something on one site only, and there it wins over the same key's action everywhere else. A site key runs one of three things:

1. an action, by its id: n = "scroll.down";
2. an element of the page, by its accessible role and name: "]" = { role = "link", name = "Next" }, looked up when you press the key. When several elements share the name, nth = 2 picks the second;
3. a list of those, run in turn: x = ["top", { role = "link", name = "Home" }].

A site key is one key, not a sequence. Never a script, and never a CSS selector. A role and a name are what a screen reader would say. They survive a redesign, and a config you share cannot use them to read a page's data. Running one is the same checked action a link hint runs.

[site."github.com".keys]
n = "scroll.down"
"]" = { role = "link", name = "Next" }

A site table matches a host (github.com), a wildcard (*.example.com, which takes the domain and every host under it) or an address prefix ("https://example.com/docs/"). When several match, the most specific wins: a prefix, then a host, then a wildcard, and a longer one over a shorter. See Configuration.

Binding a key from inside Noctiluca¶

You do not have to edit the file. On the page, press Ctrl+K ("Bind a key on this site…"). It lists the page's named controls, by role and name, then every action. Choose one with Enter, then press the key.

Choose what the key does	Press the key, and confirm

Enter binds it on this host, w on *.host (the host and every host under it), Esc cancels. If the key already does something here, you are told, and Enter replaces it on this site only. When more than one element has the name, you are told which match the key binds.

The binding is written to [site."HOST".keys] in your config file, keeping the file's comments and layout, and works at once. It needs a config file to write to and a page with a host: a local file has none.

This site's keys¶

Press K (Ctrl+Shift+K with the plain keys) for this site's keys. Enter tests one, d removes it, e binds it to another key, and s moves it between the host and *.host. A key whose element is not on this page is listed with the reason.

This site's keys	In the F1 overlay

Every action and its keys¶

Each action's id is what [keys] and site keys use. A key written as two keys with a space (g g) is a sequence: press one, then the other.

The tab actions are listed, and say "One tab for now" when you run them. Inside a list (bookmarks, site keys, the bind picker), ↑ and ↓ (or k and j) move, Enter chooses and Esc closes.