Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / cli-terminal-dashboard

CLI terminal dashboard

The CLI terminal dashboard gives terminal-first users a live WorldMonitor view without a browser. It connects to the same public data services as the web dashboard, turns those results into focused intelligence views, and keeps the terminal usable when a source or optional video player is not available.

Product role

Command entrypoint

The cli/…/run.mjs entrypoint selects the right CLI surface from the command and the terminal context. A bare command opens the dashboard only in an interactive terminal. The explicit tui and dashboard commands provide the same path, while web opens the browser dashboard and the existing data commands keep their script-friendly behavior. A forced TUI mode is available for non-interactive launchers through WM_TUI_FORCE.

The dashboard is therefore an additional client surface, not a replacement for the MCP-first command client. It can use an API key when one is present, but its public dashboard data does not require one. The package runs as a dependency-free ESM client on Node 18.17 or later.

flowchart LR
    A[worldmonitor command] --> B{Interactive terminal?}
    B -->|Yes, no command| C[Terminal dashboard]
    B -->|No, no command| D[Help text]
    A --> E[tui or dashboard]
    E --> C
    A --> F[web]
    F --> G[Hosted or local web dashboard]
    A --> H[Existing data commands]
    H --> I[Script output]

References: cli/…/run.mjs• L89-123 cli/…/core.mjs• L176-201 cli/package.json• L24-45 cli/README.md• L7-18

Terminal lifecycle

The dashboard owns a complete session from startup to clean exit. It shows a short boot phase while data loads, then runs a frame loop that combines input, refresh events, and screen updates. On exit, suspend, resize, signals, or a crash, it returns the terminal to its prior state and stops open work.

This lifecycle lets the dashboard hand the terminal to another program such as mpv and then resume without leaving raw mode, mouse capture, or the alternate screen active.

sequenceDiagram
    participant User
    participant Launcher
    participant Store
    participant App
    participant Terminal

    User->>Launcher: Start dashboard
    Launcher->>Terminal: Enter dashboard mode
    Launcher->>Store: Load boot sources
    Store-->>App: Progress and data events
    App-->>Terminal: Render views and status
    User->>App: Key, mouse, resize, or quit
    App->>Launcher: Suspend, resume, or shutdown
    Launcher->>Terminal: Restore terminal state
    Launcher->>Store: Stop refresh work

References: cli/…/index.mjs• L17-149 cli/…/app.mjs• L101-127 cli/…/app.mjs• L251-269 cli/…/app.mjs• L357-375

Service data flow

Catalog and data clients

The dashboard reads WorldMonitor service data through a small client boundary. Public bootstrap tiers provide the main dashboard state. The news digest, health, and version services provide separate status and news inputs. Military flight, vessel, and satellite data use short-lived anonymous session access unless the user supplies an API key.

The live catalog is a generated snapshot of the service's channel, webcam, world-geometry, and map-layer data. This keeps the standalone CLI independent from browser-only application code while preserving the same live-source choices and map registries. The HTTP clients do not follow redirects for service requests, which prevents an API key or anonymous session token from reaching another host.

References: cli/…/client.mjs• L1-5 cli/…/client.mjs• L25-65 cli/…/client.mjs• L67-119 cli/…/catalog.generated.json• L1-11 cli/…/catalog.generated.json• L12-23 scripts/sync-tui-catalog.mjs• L229-245

Refresh and source state

The data store gives each service source its own freshness, loading, error, and retry state. Boot loads the core sources in a useful order. Later refreshes run in the background, and view-specific sources load only while their view needs them.

This model limits service load and makes partial data useful. A failed source does not hide the whole dashboard; the System view can show the error while other views continue to work.

References: cli/…/store.mjs• L32-84 cli/…/store.mjs• L86-127 cli/…/base.mjs• L60-70 cli/…/system.mjs• L83-106

Data shaping

Selectors form a stable display layer between service payloads and views. They order news, group market data, rank risk signals, turn events into map markers, format ages and values, and choose playable video sources. Views use these display models instead of interpreting service responses independently.

The separation keeps service field changes concentrated in the data layer and allows the selectors to run against fixture data without a terminal.

References: cli/…/select.mjs• L73-115 cli/…/select.mjs• L117-166 cli/…/select.mjs• L210-255

Interactive views

Dashboard views

The dashboard groups related WorldMonitor signals into views that support a common pattern: focused panes, selectable rows, keyboard movement, mouse clicks, and links that can open outside the dashboard. The Map view adds a geographic surface for those signals, while the System view provides the health and freshness context needed to judge the other views.

ViewProduct purpose
OverviewGive a fast global picture through the map, brief, stories, markets, and theater posture.
MapExplore global signals as geographic layers on a flat map or rotating globe.
BriefRelate AI brief story lines to cited sources and matching live coverage.
NewsLet the user move from ranked categories to headline detail and source links.
MarketsCompare market groups, price changes, trends, and macro signals.
ConflictBring together instability, conflict events, unrest, posture, and related signals.
Air & SeaShow military flights, airport delays, vessel activity, chokepoints, and shipping stress.
CyberSummarize cyber threats, outages, traffic anomalies, and service status.
ClimateSurface earthquakes, hazards, fires, weather alerts, and climate measures.
PredictPresent prediction markets and scenario forecasts by domain.
LiveBrowse news channels and webcams with several playback choices.
IntelCombine topic feeds, sanctions pressure, advisories, and other cross-source signals.
SystemShow platform health, source freshness, appearance settings, and player status.

References: cli/…/index.mjs• L1-30 cli/…/overview.mjs• L14-18 cli/…/brief.mjs• L67-73 cli/…/news.mjs• L10-13 cli/…/airsea.mjs• L10-13 cli/…/live.mjs• L14-17 cli/…/intel.mjs• L10-13 cli/…/system.mjs• L10-13

Navigation works from both keyboard and mouse input. Number keys and tab movement change views. Pane focus controls which list receives movement, while selection and activation open a story, source, stream, or map record when the view supports it. Narrow terminals hide some panes or the map layer panel rather than forcing an unusable layout.

The app also provides shared help, refresh, theme, animation, detail-overlay, and web-dashboard actions. This gives every view a common interaction model while allowing views such as Brief, News, Map, and Live to add domain-specific controls.

References: cli/…/app.mjs• L129-197 cli/…/app.mjs• L219-355 cli/…/detail.mjs• L64-90 cli/…/base.mjs• L18-123 cli/…/brief.mjs• L134-144 cli/…/news.mjs• L40-56 cli/…/map.mjs• L198-329 cli/…/live.mjs• L75-103

Geographic map

The Map view turns static geographic registries and live service records into selectable map features. It supports a flat world map and a rotating globe, with layers for infrastructure, military activity, hazards, society, mobility, economy, and technology.

The map connects visual exploration to record detail. Hover highlights a feature's layer, clicking pins it, search jumps to a feature or country, and Enter opens a detail view. Enabled layers request only the live sources they need, so the map can grow without making every session load every feed.

Satellite imagery is an optional backdrop rather than the source of map meaning. NASA GIBS imagery can show Blue Marble, current true colour, or night lights, while WorldMonitor features remain interactive above it.

References: cli/…/map.mjs• L22-95 cli/…/map.mjs• L198-372 cli/…/map.mjs• L490-548 cli/…/layers.mjs• L15-24 cli/…/layers.mjs• L507-541 cli/…/imagery.mjs• L9-15 cli/…/backdrop.mjs• L7-22 cli/…/catalog.generated.json• L1339-1350

Preferences and video

Preferences

Preferences preserve the user's presentation choices across sessions. They include the selected theme, animation state, last view, and map state such as position, active layers, imagery, and sidebar visibility. The file lives under the XDG configuration directory and accepts only known display fields, so credentials never enter the preferences file.

Command options can override preferences for one session. The dashboard saves changes made during use, including theme selection, animation state, the last active view, and map changes made before exit.

References: cli/…/prefs.mjs• L1-33 cli/…/index.mjs• L25-29 cli/…/app.mjs• L78-125 cli/…/map.mjs• L72-95

Video support

The Live view treats video as an external capability. It prefers HLS or a current YouTube source from the catalog, then sends that URL to mpv; yt-dlp helps mpv resolve YouTube streams. Users can play in the terminal, open a separate player window, or use the browser.

If mpv is missing or a stream fails, the dashboard keeps the session usable and offers a browser fallback or another catalog source. External links are limited to HTTP and HTTPS URLs.

References: cli/…/live.mjs• L52-137 cli/…/video.mjs• L26-87 cli/…/video.mjs• L90-109 cli/…/catalog.generated.json• L12-23 cli/…/detail.mjs• L15-16

Test contracts

Client and data contracts

The data tests protect alignment with WorldMonitor services at the client boundary. They verify public requests, anonymous session minting and renewal, API-key preference, source boot order, refresh limits, lazy loading, retry state, and clean client shutdown. Selector tests also verify that representative service payloads become usable news, market, map, risk, and video models.

The redirect tests add a security contract across the CLI, REST client, and TUI client. Service requests fail at a redirect instead of forwarding credentials, while OpenAPI listing may follow a redirect and removes the key when the redirect changes origin. These checks catch silent drift in authentication, endpoint use, freshness rules, and payload interpretation before it reaches a rendered view.

References: cli/…/tui-data.test.mjs• L53-208 cli/…/tui-data.test.mjs• L210-266 cli/…/redirect.test.mjs• L41-79 cli/…/client.mjs• L44-50 cli/…/run.mjs• L57-71

Terminal and view contracts

Terminal tests protect color fallback, text width, clipping, screen diffs, key decoding, mouse decoding, and wide-character cell alignment. App tests render every view at wide and narrow sizes, drive the main navigation paths, verify settings persistence, check lazy view sources, and exercise Live fallbacks. Map tests add contracts for projections, world geometry, layer features, imagery caching, satellite tracks, search, hover, pinning, detail records, and map preference persistence. Launch tests verify that quitting during boot aborts work and restores terminal state.

The package tests also protect the published command wiring, version alignment, request headers, and the parity of curated commands across supported SDK surfaces. The redirect tests keep those command and client surfaces aligned on credential handling.

References: cli/…/tui-term.test.mjs• L19-162 cli/…/tui-app.test.mjs• L51-310 cli/…/tui-map.test.mjs• L79-234 cli/…/tui-map.test.mjs• L236-451 cli/…/tui-map.test.mjs• L525-885 cli/…/tui-launch.test.mjs• L30-66 tests/cli-package.test.mjs• L20-105 tests/cli-curated-commands-parity.test.mjs• L28-41 cli/…/redirect.test.mjs• L1-9

The terminal dashboard is one external client in the wider WorldMonitor product. The desktop and external clients page gives the parent view. Related surfaces include the Tauri desktop application, browser plugin country intelligence, SDK client libraries, and Zapier automation integration.

Change checklist

When these files or sections are changed, remember to consider these:

  • Update the generated TUI catalog when live channel, webcam, world geometry, or map-layer inputs change. Keep the catalog check and its source list aligned.
  • Keep the source table, selector expectations, and System view consistent when an API endpoint, auth mode, refresh interval, or payload shape changes.
  • Keep view order, numeric shortcuts, tab labels, help text, and headless navigation expectations aligned when adding or moving a view.
  • Keep map layer definitions, layer-source activation, catalog records, map controls, and feature detail fields aligned when adding or changing a geographic layer.
  • Keep imagery mode labels, GIBS request rules, cache behavior, and map shutdown behavior aligned when changing satellite backdrop support.
  • Preserve the anonymous-session and API-key distinction when changing authenticated flight, vessel, or other on-demand sources.
  • Preserve the no-redirect credential boundary when changing CLI requests, spec listing, or TUI client transport.
  • Recheck terminal cleanup and mpv suspend/resume behavior when changing launch, signal, or video control paths.

Important failure modes

TriggerConsequenceGuard
Generated live catalog is staleThe Live view can show old channels, webcams, or map data.Catalog freshness check in scripts/sync-tui-catalog.mjs and TUI fixture coverage.
Anonymous session expires or is rejectedAir & Sea data fails until the client mints a new session.Client retry on an authenticated 401 and data-client tests.
A source returns an errorOne pane can be empty or stale while the rest of the dashboard remains usable.Per-source error state, retry backoff, and System view reporting.
A map layer enables a source without declaring itThe layer looks empty and the System view can hide the missing data path.Layer-source mapping and feature-count tests.
A map view crosses the antimeridian or receives stale imageryThe map can show a wrap streak or a misleading backdrop.Projection, tile extent, cache, and imagery compositing tests.
A terminal renders a wide marker or label as one cellLater text shifts and the dashboard becomes hard to read.Screen cell-width handling and map-wide-character tests.
mpv or yt-dlp is unavailableTerminal playback cannot start.Player detection and browser fallback.
A service redirects a requestThe request fails instead of risking credential forwarding.Manual redirect handling in the CLI and TUI clients, with redirect tests.
Dashboard exits during boot or playbackTerminal state or open requests could be left behind.Central shutdown, request aborts, and launch lifecycle tests.

Key files

FileWhy to read it
cli/…/run.mjsDefines how the CLI chooses the terminal dashboard, web dashboard, or script path.
cli/…/core.mjsDefines command parsing, request planning, service endpoints, and CLI contracts.
cli/…/index.mjsShows the dashboard session lifecycle and terminal cleanup boundary.
cli/…/app.mjsDefines shared state, navigation, input, rendering, and overlays.
cli/…/client.mjsDescribes public requests, session access, API-key use, redirect handling, and shutdown.
cli/…/store.mjsDefines boot order, refresh behavior, lazy sources, and source health.
cli/…/select.mjsShows how service payloads become view-ready models.
cli/…/catalog.generated.jsonShows the generated boundary for live channels, webcams, geometry, and map data.
cli/…/index.mjsLists the product views and their navigation order.
cli/…/map.mjsShows how geographic data becomes an interactive map and globe.
cli/…/layers.mjsDefines the product layer groups and their live or catalog data needs.
cli/…/imagery.mjsDescribes the optional NASA imagery choices and cache boundary.
cli/…/brief.mjsExplains the brief story-line and related-coverage experience.
cli/…/detail.mjsDefines the shared record detail view and safe external-link boundary.
cli/…/live.mjsExplains the Live view's source selection and playback actions.
cli/…/prefs.mjsDefines the persistent display settings and credential boundary.
scripts/sync-tui-catalog.mjsDefines the source-to-CLI catalog boundary.
cli/…/redirect.test.mjsProtects credential handling across redirects in CLI and TUI clients.
cli/…/tui-app.test.mjsShows the cross-view rendering and interaction contract.
cli/…/tui-map.test.mjsShows the map, imagery, geometry, detail, and persistence contracts.
cli/…/tui-term.test.mjsShows the terminal width, color, screen, and input contracts.