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.
| View | Product purpose |
|---|---|
| Overview | Give a fast global picture through the map, brief, stories, markets, and theater posture. |
| Map | Explore global signals as geographic layers on a flat map or rotating globe. |
| Brief | Relate AI brief story lines to cited sources and matching live coverage. |
| News | Let the user move from ranked categories to headline detail and source links. |
| Markets | Compare market groups, price changes, trends, and macro signals. |
| Conflict | Bring together instability, conflict events, unrest, posture, and related signals. |
| Air & Sea | Show military flights, airport delays, vessel activity, chokepoints, and shipping stress. |
| Cyber | Summarize cyber threats, outages, traffic anomalies, and service status. |
| Climate | Surface earthquakes, hazards, fires, weather alerts, and climate measures. |
| Predict | Present prediction markets and scenario forecasts by domain. |
| Live | Browse news channels and webcams with several playback choices. |
| Intel | Combine topic feeds, sanctions pressure, advisories, and other cross-source signals. |
| System | Show 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 and interaction
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
Related client surfaces
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
mpvsuspend/resume behavior when changing launch, signal, or video control paths.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Generated live catalog is stale | The 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 rejected | Air & Sea data fails until the client mints a new session. | Client retry on an authenticated 401 and data-client tests. |
| A source returns an error | One 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 it | The 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 imagery | The 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 cell | Later text shifts and the dashboard becomes hard to read. | Screen cell-width handling and map-wide-character tests. |
mpv or yt-dlp is unavailable | Terminal playback cannot start. | Player detection and browser fallback. |
| A service redirects a request | The request fails instead of risking credential forwarding. | Manual redirect handling in the CLI and TUI clients, with redirect tests. |
| Dashboard exits during boot or playback | Terminal state or open requests could be left behind. | Central shutdown, request aborts, and launch lifecycle tests. |
Key files
| File | Why to read it |
|---|---|
| cli/…/run.mjs | Defines how the CLI chooses the terminal dashboard, web dashboard, or script path. |
| cli/…/core.mjs | Defines command parsing, request planning, service endpoints, and CLI contracts. |
| cli/…/index.mjs | Shows the dashboard session lifecycle and terminal cleanup boundary. |
| cli/…/app.mjs | Defines shared state, navigation, input, rendering, and overlays. |
| cli/…/client.mjs | Describes public requests, session access, API-key use, redirect handling, and shutdown. |
| cli/…/store.mjs | Defines boot order, refresh behavior, lazy sources, and source health. |
| cli/…/select.mjs | Shows how service payloads become view-ready models. |
| cli/…/catalog.generated.json | Shows the generated boundary for live channels, webcams, geometry, and map data. |
| cli/…/index.mjs | Lists the product views and their navigation order. |
| cli/…/map.mjs | Shows how geographic data becomes an interactive map and globe. |
| cli/…/layers.mjs | Defines the product layer groups and their live or catalog data needs. |
| cli/…/imagery.mjs | Describes the optional NASA imagery choices and cache boundary. |
| cli/…/brief.mjs | Explains the brief story-line and related-coverage experience. |
| cli/…/detail.mjs | Defines the shared record detail view and safe external-link boundary. |
| cli/…/live.mjs | Explains the Live view's source selection and playback actions. |
| cli/…/prefs.mjs | Defines the persistent display settings and credential boundary. |
| scripts/sync-tui-catalog.mjs | Defines the source-to-CLI catalog boundary. |
| cli/…/redirect.test.mjs | Protects credential handling across redirects in CLI and TUI clients. |
| cli/…/tui-app.test.mjs | Shows the cross-view rendering and interaction contract. |
| cli/…/tui-map.test.mjs | Shows the map, imagery, geometry, detail, and persistence contracts. |
| cli/…/tui-term.test.mjs | Shows the terminal width, color, screen, and input contracts. |