Server, Web, and TUI

This is the part of the toolkit that turns it from “a pile of commands” into one reusable local application.

Server

gran serve starts a long-lived local Gran 👵🏻 server on one shared app instance.

High-level API surface:

• health and server info
• auth login, refresh, lock, unlock, and mode switching
• shared state and live event streaming
• folder and meeting queries
• export job listing and reruns
• notes and transcript export triggers

Security defaults:

• local network mode by default
• optional password protection
• trusted-origin checks for browser requests
• warnings when you expose the server on lan without a password

Background Service

gran service start wraps the same local HTTP server and sync loop in a detached background process.

Use it when you want:

• continuous sync without keeping a foreground terminal busy
• one durable local runtime for browser and terminal clients
• a simple start, status, stop lifecycle instead of a manually supervised serve

Examples:

gran service start
gran service start --network lan --password "change-me"
gran service status
gran service stop

The service persists its discovery metadata in the shared Gran 👵🏻 data directory, so other surfaces can find it automatically.

Web

gran web prefers the reusable background service: it will attach to the running service if one exists, or start that service for you before opening / in your default browser. Pass --foreground when you explicitly want a throwaway foreground browser runtime instead.

Examples:

gran web
gran web --meeting 1234abcd
gran web --foreground --open=false --port 4096
gran web --open=false --port 4096
gran web --network lan --password "change-me"

If you do not pass runtime overrides like --port, --hostname, --network, --password, or --sync-interval, gran web will stay on the shared service path instead of starting another local runtime.

The browser workspace gives you:

• a calmer home dashboard for recent meetings, sync health, and what needs attention
• folder views, meeting views, and a separate search page instead of one giant meeting rail
• quick open when you already know the title or id
• notes, transcript, metadata, and raw tabs
• focused settings for connection, knowledge bases, and advanced tools
• export actions and recent export jobs
• auth session controls without crowding the main meeting view
• the same shared local HTTP transport that attach and other local clients use

TUI

gran tui starts a full-screen terminal workspace on the shared app core.

Main controls:

• h / l, left / right, or Tab to switch focus
• j / k or arrow keys to move within lists
• / or Ctrl+P to open quick open
• a to open auth session actions
• 1-4 to switch detail tabs
• r to refresh
• q to quit

Attach

gran attach connects a terminal workspace to an existing local server instead of starting a second isolated app. If the background service is already running, you can omit the URL entirely.

Examples:

gran service start
gran attach
gran serve --port 4096
gran attach http://127.0.0.1:4096
gran attach http://127.0.0.1:4096 --meeting 1234abcd

Runtime Boundaries

The current single-package repo still keeps transport and persistence boundaries explicit:

• one shared local data directory
• one versioned local HTTP transport contract
• one client handshake that validates protocol compatibility before attaching