Client Overview

Summary

The 2Wee client is a terminal application that connects to any 2Wee-compatible server. It renders server-driven screens, handles keyboard input, and sends changes back. You download it, point it at a server, and use it.

Installation

Install (macOS, Apple Silicon)

curl -sL https://docs.ktr.fo/install.sh | sh

This downloads the binary, extracts it to /usr/local/bin/2wee, and clears the macOS quarantine flag. It prompts for sudo if needed.

Update

Run the same command. The install script overwrites the existing binary.

Build from source

Requires Rust (stable). From the project root:

cargo build --release -p two_wee_client

The binary is at target/release/two_wee_client.

Platform support

Platform	Status
macOS (Apple Silicon / arm64)	Supported
macOS (Intel / x86_64)	Build from source
Linux	Build from source
Windows	Not tested

macOS Gatekeeper

The install script handles Gatekeeper automatically. If you download the binary manually, run:

xattr -d com.apple.quarantine /usr/local/bin/2wee

Connecting to a server

# Default: connects to http://localhost:3000
2wee

# Specify a server
2wee http://your-server:3000

# Or use an environment variable
export TWO_WEE_SERVER=http://your-server:3000
2wee

How it works

ScreenContract

Every server response is a ScreenContract — a JSON document that describes one screen. The layout field determines how the client renders it:

Layout	Purpose
Menu	Navigation menu with tabs and items
List	Scrollable table for browsing records
Card	Single-record form with sections and fields
HeaderLines	Card with an attached editable grid (e.g., Sales Order with line items)
Grid	Full-screen editable grid (e.g., payment journals, batch entry)

The client does not choose layouts. The server tells it what to show.

Screen stack

The client maintains a stack of screens. Opening a new screen pushes it onto the stack. Pressing Esc pops back to the previous screen:

Menu → Customer List → Customer Card → Ledger Entries → Ledger Entry Card
  ← Esc ← Esc ← Esc ← Esc

Form-level save

The user edits fields freely. No data is sent to the server until the user presses Ctrl+S. The client collects all changed fields into a changeset and sends it as a single POST. The server responds with a fresh ScreenContract reflecting the saved state.

No per-field round-trips during editing. The user can edit 10 fields, change their mind on 3 of them, and save once.

Environment variables

Client

Variable	Default	Description
TWO_WEE_SERVER	http://localhost:3000	Server URL. Can also be passed as a CLI argument.

Token storage

The client stores authentication tokens per-server at:

~/.2wee/tokens/<hash>

Where <hash> is a hash of the server URL. File permissions are chmod 600. This allows connecting to multiple servers simultaneously with separate authentication states.