dat-thang/docs/dat-thang.1

.TH DAT-THANG 1 "October 2026" "dat-thang v0.0.002" "User Commands"
.SH NAME
dat-thang \- SDL2 local archive and peer discovery client
.SH SYNOPSIS
.B dat-thang
.RI [ --archive DIRECTORY ]
.RI [ --site HOSTNAME ]
.RI [ --offline ]
.br
.B dat-thang --version
.SH DESCRIPTION
dat-thang is the SDL2 graphical client for browsing a local filesystem directory,
explicitly loading or creating Dat archives, and controlling the client's online
discovery state. The top-left switch applies to the whole client. OFF leaves all
loaded archive topics, unannounces when possible, closes the network socket, and
clears peer state. ON connects the client and announces archives in its loaded
archive list. Selecting an archive or browsing a directory does not toggle the
client's network state or create an archive.
.PP
Version v0.0.002 is a prototype in pre-alpha.
.PP
The pane to the right of the Merkle graph navigates the local filesystem.
Click a directory to enter it; navigation alone never creates or shares an
archive. The bottom bar displays the selected filename and directory. Use
F9 or IMPORT DAT to load an existing archive from the selected directory, or
CREATE NEW DAT to deliberately create one. Loaded archives are remembered in
the archive switcher and shared whenever the client is online. Secret signing keys are stored under
.B $HOME/.dat/secret_keys/
using Dat Desktop's sharded discovery-key paths, with one raw secret file per
feed. See the installed key-management documentation.
.PP
Click the local SITE field while an archive is loaded to assign that archive a
dat-dns hostname. Type the hostname and press Return to save a local alias; this
client resolves it immediately. The confirmation dialog copies the corresponding
dat-dns value to the clipboard. Public Dillo-compatible resolution uses the
hostname's HTTPS /.well-known/dat response, whose first line is dat:// followed
by the 64-digit archive key and whose optional second line is TTL=<seconds>.
Escape cancels hostname editing. The site field can also display the
hostname supplied with --site. Archive displays the selected archive key in
hexadecimal or compact Base32768 form; click the format control to switch and
COPY to copy its dat:// address. Version shows the active
selected metadata-feed version and latest version; click the arrows to check out
another recorded version. The matching Merkle view shows the feed's block count
and a tree view of its active version.
The peer pane distinguishes discovered peer announcements from authenticated
connected peers with a marker on each buddy-list row. Double-click a peer to
open Cable-thang's encrypted direct-message pane. Copy the desired dat:// link
from the local ARCHIVE field, paste it into chat with Ctrl+V, and press Enter
to send it. Click a received dat:// message to copy it, then click the
right-hand ARCHIVE field and press Ctrl+V followed by Enter to begin importing
into the currently selected local directory. The
incoming archive appears in the lower transfer table while peers are found and
metadata downloads. The current Cesspool message record is Cable-specific and
is not Cabal feed interoperability.
.PP
By default dat-thang listens on UDP 3282 and cable-thang listens on UDP 3000,
the stable ports used by Cesspool LAN discovery. If a preferred port is busy,
the client chooses another known Cesspool port. Set DDAT_PORT to pin the local
port. With no configured rendezvous, discovery is limited to the local network;
across networks, both clients need a reachable Cesspool node.
The YOU panel shows the selected room's local Cable feed address. Like Cabal,
the key is scoped to that room's local feed and remains stable across restarts;
room and optional admin keys are separate. The CLI prints the full address with
.BR "cable whoami <room-address>" .
The panel also shows connected peers, discovered peers, and the total number of
loaded local directories available for sharing.
The lower table lists loaded archives as well as active transfers. Its progress
column is a bar: local archives are complete, while transfer bars count received
blocks against the peer's advertised feed lengths. Received blocks are checked
against SLEEP proofs and saved in per-feed .remote caches for later sessions.
For each local archive, TITLE and DESCRIPTION come from its root `dat.scm`
S-expression. Missing fields fall back to the directory name and archive key.
.SH OPTIONS
.TP
.B --version, -v
Print \fBdat-thang v0.0.002 (prototype, pre-alpha)\fR and exit.
.TP
.B --archive DIRECTORY
Start in DIRECTORY. If it contains an existing .dat archive, load that archive;
otherwise browse the directory without creating or sharing an archive. Defaults
to the current directory.
.TP
.B --site HOSTNAME
Display HOSTNAME in the site field.
.TP
.B --offline
Start with peer discovery disabled, even when the directory already has an
archive.
.TP
.B --smoke
Render one frame and save build/linux/dat-thang-smoke.bmp on GNU/Linux or
build/windows/dat-thang-smoke.bmp on Windows. Intended for headless
render checks.
.SH CONTROLS
.TP
.B F1
Show this manual page in the client. Use Up/Down or the mouse wheel to scroll;
press Escape to close it.
.TP
.B F9
Load an existing Dat archive from the selected directory. This does not create
an archive or start discovery; use ON to share it.
.TP
.B CREATE NEW DAT
Create a Dat archive for the selected local directory and import its current
files. Use ON to start discovery after creation.
.TP
.B IMPORT DAT
With no remote address entered, load an existing archive in the selected local
directory. To import a remote archive, enter a dat:// URL in the
right-hand SITE or ARCHIVE field, select an empty destination directory, then
click IMPORT DAT. Verified metadata and content blocks are cached below that
directory's .dat folder.
.TP
.B Escape
Toggle the client menu.
.TP
.B Mouse
Click OFF to disconnect all peers and go offline. Click ON to bring the client
online and announce loaded archives. With no loaded archives it still connects
to Cesspool without announcing a topic. Archive selection changes the local view.
Click entries in the right-hand pane to navigate
directories or select a filename. Click ARCHIVES above the pane to switch
between known local archives. The directory pane has its own scrollbar and
mouse-wheel scrolling. The bottom archive/transfer table includes known shared
archives and active transfers; its horizontal scrollbar can be dragged, and
the mouse wheel scrolls rows (Shift+wheel scrolls columns). Enter a remote dat:// address in the mirrored
SITE or ARCHIVE field before selecting IMPORT DAT. Drag transfer-table header dividers to resize
columns; use Shift+wheel over the table to scroll horizontally. The bottom
track indicates horizontal position. Right-click opens load, create, and
copy-address actions. COPY includes the selected archive version in its dat://
link.
.SH NETWORK
The client reads endpoints saved by \fBdat bootstrap add host:port\fR or
\fBdat bootstrap set host:port\fR from
$HOME/.config/dat-gpt/bootstrap and also accepts DDAT_BOOTSTRAP as a comma- or
semicolon-separated list. The Settings menu also edits this endpoint and
restarts discovery immediately. Run \fBcesspool-bootstrap\fR on the rendezvous
host with \fB--advertise HOST:PORT\fR to print the address clients should use.
It does not query an outside service for a public IP. Allow the chosen UDP
port through the host firewall and router.
This is Cesspool rendezvous for these C clients; it is not a BitTorrent DHT
node and cannot be substituted for the historical JavaScript Dat bootstrap
servers. OFF leaves every archive topic and closes the Cesspool socket. ON
starts archive discovery; the indicator turns green only after a Cesspool
response or connected peer.
.SH ENVIRONMENT
.TP
.B DDAT_BOOTSTRAP
Comma- or semicolon-separated Cesspool rendezvous endpoints, for example
127.0.0.1:3282.
Saved endpoints from dat bootstrap add are also loaded automatically.
.TP
.B DDAT_PORT
UDP listening port. If unset, Cesspool selects an available default port.
.TP
.B DAT_THANG_MANPAGE
Optional path to the dat-thang manual source displayed by F1.
.SH MENU
Escape opens the vertical Settings, Return, Exit menu. Settings contains
persistent controls for the default copied-address format, sonar audio, and
connecting on startup. Use Up/Down and Enter, or click an item. Return resumes
the client; Exit closes it. Escape from Settings returns to the menu.
.SH AUDIO
Click the speaker icon to play and send a two-second low square-wave cue.
Clicking the dolphin plays and sends a one-second arpeggiated chiptune cue.
The dolphin cue goes to connected authenticated peers. The speaker cue refreshes
discovery for the active archive and is sent to discovered peers as their secure
sessions become ready. Peers play received cues locally; the speaker response
causes the peer to return one dolphin chirp, which plays at the sender and marks
the peer found. The waveform viewer draws samples captured from the actual SDL
audio output.
.SH BUILD DATE
The header shows the program build date in Discordian format (ddate). The
calendar conversion is compiled directly into dat-thang; no external ddate
program or runtime lookup is needed on Windows or GNU/Linux.
.SH DILLO
To install the Dillo DPI helper for the current Dillo source, build with make, run make install using the
same PREFIX as Dillo, add proto.dat=dat/dat.dpi to ~/.dillo/dpidrc, and restart
Dillo. The helper first reads its local archive cache at
~/.dillo/dat/archives/XX/<key-tail>. On a cache miss, it can use the configured
Cesspool bootstrap to find a peer, authenticate the SLEEP session, and fetch
the archive metadata and content feeds into that cache. Start the bootstrap
before the clients so the first archive announcement is recorded. The Linux
side-by-side runbook uses the default GNU/Linux output path, build/linux, to
keep its objects separate from Windows artifacts in a shared checkout.
.SH SEE ALSO
ddat(1), dat(1)