Getting Started

Install, open the REPL, and read your server’s live state. A few minutes, nothing to configure.

Install

suctl is a single binary. No runtime, no dependencies.

# linux · macos · arm
curl -fsSL https://suctl.com/install | sh

# windows
irm https://suctl.com/install.ps1 | iex

Both installers resolve the latest release, verify its checksum, and hand off to suctl install (which owns the on-disk layout). Pin a version with SUCTL_VERSION=v0.6.0, or point at a fork with SUCTL_REPO=owner/name.

Upgrade

Once installed, suctl updates itself in place — the same resolve-and-verify flow as the installer, no script needed:

sudo suctl upgrade        # -y to skip the confirmation prompt

It compares the latest release against the running build, and when newer downloads the matching archive, verifies its checksum, swaps the binary in place (atomic on Unix; a self-rename on Windows, with the old image cleared on the next run), and refreshes the bundled modules. Any module setup or upgrade hooks run on your next suctl invocation. Honours the same SUCTL_VERSION / SUCTL_REPO overrides.

First session

suctl

You land on the home page. The title bar reads the inventory at a glance — N active · M ready. On a fresh install nothing is active yet, so the page is empty and shows 0 active · M ready: suctl has found modules, but none are running.

Navigating

Everything in suctl is a row. ↑↓ moves the selection between rows; ←→ or tab step across the selected row to its fields and buttons; ⏎ enters whatever is selected. On the home and survey pages just start typing to filter the rows — there is no mode to enter and no / to press. esc pops back one page; Alt+q quits.

Activate a module

Ready means suctl discovered the module and its requirements are met — it is not running until you say so. Tab to the inventory button on the bottom row and press ⏎.

Inventory is itself a survey: one row per discovered module. Focus a module (⏎) and its actions include activate. Activate the modules you want, and each one’s surface appears as a row back on the home page — only active modules show there.

If a module depends on capabilities from others, suctl lists every module that will activate alongside it and asks you to confirm before proceeding — nothing starts behind your back.

From there the REPL is one loop, three moments:

Survey — the landscape

Enter a module and you see its whole domain at once — for the nginx module, every managed domain with its blocks, SSL and status columns. This is read live from the source of truth at the moment you enter; nothing is cached, nothing was “synced earlier”.

Type to filter rows instantly. Toggle facet chips (‹ active · ssl expiring · suspended ›) to ask the module for a sliced landscape — show me every domain with an expiring certificate is one keypress, and the filtered survey is itself the answer. Many sessions end right here, question answered, without ever selecting anything.

Focus — the detail

Select a subject (⏎) and you see everything the module knows about that one thing — again read live at the moment of selection.

Act — what is possible

At the bottom of the focus view sit the available actions — computed from the subject’s current state, not a fixed menu. A suspended domain offers unsuspend; suspend is absent, not greyed out. ←→ picks an action, ⏎ invokes it, and you return to the survey, re-read live so you see the result.

That is the whole interface — the same loop on every surface, the same handful of keys throughout.

Where to go next

• Writing your first module — give suctl a new domain to survey, in any language.
• Concepts — why the REPL refuses to cache, and the standard every module is held to.
• Reference — normative specifications for module authors, starting at core architecture. You don’t need these to use suctl.