Suwu CLI

Overview

Every suwu subcommand talks to the running server over a local Unix socket, so a shell on the server can put things on your screen. Run suwu help for the full list, or suwu help <command> for one command's flags.

Commands that reach the server accept --sock <path> if the socket is not at the default ~/.suwu/suwu.sock (override with SUWU_SOCK_PATH).

suwu send

Post a notification to the Suwu web UI from any terminal or script.

# Simple notification
suwu send "Build completed successfully"

# Pipe stdin as the notification body
echo "Tests passed" | suwu send

# Pipe a file
cat changelog.txt | suwu send

Notifications appear in the browser's notification panel. With no message argument, stdin is read to EOF and sent as one message, keeping internal newlines; one trailing newline is dropped. Messages are capped at 1 MiB of encoded JSON — an oversized one is rejected before anything is sent.

Use Cases

• Build notifications — append suwu send "Build done" to your build script.
• CI/CD alerts — pipe pipeline output to suwu send.
• Monitoring — send alerts when a health check fails.
• Long tasks — make && suwu send "Make complete".

suwu forward

Open a port-forwarding tile from the command line.

# Forward port 3000
suwu forward 3000

# Forward to a different remote port
suwu forward 8080 3000

# UDP forwarding
suwu forward --proto udp 5353

# List what is running, or stop one
suwu forward --list
suwu forward --stop 3000

See Port Forwarding for the tile itself.

suwu open

Open a file or directory in the running Suwu session — in the file browser or the viewer.

suwu open .                  # a directory in the file browser
suwu open README.md           # a file in the viewer
suwu open ~/Documents/report.pdf

suwu gitgraph and suwu diff

Shorthands for the two review tiles:

suwu gitgraph .              # the repository's commit graph
suwu diff old.go new.go       # a side-by-side comparison

suwu code

Open files in the Code Explorer tile, with specific lines highlighted — the shortest path from a stack trace to the code it points at. Ranges are 1-based and inclusive.

# Open one file
suwu code server.go

# Highlight a range
suwu code server.go:400-460

# Several ranges, in several files
suwu code server.go:12,40-55 handler.go:7

# Root the explorer at a directory
suwu code ./pkg

suwu gq

Run a JavaScript file in a request-scoped QuickJS sandbox: a fresh isolate, scoped filesystem roots, an optional JSON input, and a hard deadline. It is the same runtime that renders extension tiles.

# Transform input into a JSON result
printf 'function handler(i){return {doubled: i.n * 2};}' > /tmp/double.js
suwu gq --input '{"n":21}' --print-result /tmp/double.js

# Read a file from a mounted root
suwu gq --root /app=./src --print-result /tmp/read.js

# Call an API (loopback and private hosts need --allow-private)
suwu gq --allow-net --print-result /tmp/fetch.js

# Machine-readable output
suwu gq --result-file /tmp/out.json --input '{"n":21}' /tmp/double.js

Exit codes are meaningful: 0 success, 1 script error, 2 timeout, 3 output limit, 64 usage. See gqjs Script Runner for the script contract and the full flag list.

suwu agent

Detect the AI coding agents on this machine and install the suwu-tools skill into them, so an agent can drive your running Suwu session — open tiles, read output, post a notification — instead of guessing at a browser.

suwu agent                        # detect, then pick agents in a TUI
suwu agent --list                 # show which agents were detected
suwu agent --agent pi,opencode
suwu agent --agent claude --global  # user-global skills instead of this repo
suwu agent --print > suwu-tools.md

suwu use

Run a command with DISPLAY pointed at an X display the server can reach — the GUI-tool launcher for a headless box. A TUI asks which display to use when there is more than one.

suwu use xterm
suwu use firefox
suwu use chromium --new-window https://localhost:3000

suwu serve, suwu onboard, and suwu daemon

Running the server, setting it up, and keeping it in the background:

suwu serve                       # HTTPS on :8181
SERVER_MODE=http suwu serve      # HTTP on :8180
SERVER_MODE=https+http suwu serve # both

suwu onboard                      # interactive setup wizard
suwu onboard --tls                # re-run one section only

suwu daemon start                 # background process (data: ~/.suwu)
suwu daemon status
suwu daemon logs

See Get Started for the setup walkthrough and Security & Access for modes, passwords, and tokens.

suwu gencerts

Generate the TLS pair used for HTTPS access — a local CA plus a leaf certificate for this machine. suwu onboard calls it for you; run it directly to issue certificates for extra hosts.

suwu gencerts
suwu gencerts --hosts localhost,192.168.1.100
suwu gencerts --out /tmp/certs --no-env

suwu upgrade

Update the Suwu binary to the latest release:

suwu upgrade            # upgrade if a newer version exists
suwu upgrade --check    # just report
suwu upgrade --force    # re-download even if up to date

If the daemon is running, it is stopped for the upgrade and started again afterwards. See Upgrading for details.

suwu install

Put a background or an extension into the data directory — from the first-party catalog or from a zip:

# interactive picker (needs a terminal)
suwu install

# name them outright, or list the catalog
suwu install --github eye note hn-top-stories
suwu install --list

# one kind, everything of that kind
suwu install --github --kind background --all

# from an archive; the zip root is extension/<id>/… or background/webgpu/<id>/…
suwu install --extension eye.zip
suwu install --background matrix-rain.zip

# report without writing, or replace an existing install
suwu install --extension eye.zip --dry-run
suwu install --extension eye.zip --force

Nothing needs a server restart: both registries are read from disk per request, so an install is live at once and opening System Settings re-reads the lists. Only a tile that was already open needs a tab reload. A missing or duplicate name is reported with a pointer to --list, and a rate-limited GitHub API falls back to the cached catalog.

See Extensions and Backgrounds for what gets installed.

suwu background build

Compile a WGSL entry shader — resolving its whole import graph — into the JavaScript module a custom WebGPU background needs. The compiler is embedded in the binary, so there is no Node toolchain to install.

suwu background build shaders/cosmos.wgsl > shaders/cosmos.shader.js

See Backgrounds for the directory layout a background must have.