docs/cli.mdx
worldmonitor is the official command-line client for the World Monitor global-intelligence API. It's a thin, dependency-free wrapper over the MCP server (the recommended agent surface) with a REST escape hatch, so you can pull briefs, risk scores, and conflict / cyber / market / news feeds from a shell script or an agent without writing a single line of HTTP plumbing. It ships as ESM and runs on Node 18+.
The source lives in cli/ in the main repository and is published to npm on every cli-v* release tag.
Maintainers can follow the CLI release runbook when cutting a new npm version.
Prefer a library over a shell? The same client ships as official SDKs for Python, Ruby, and Go.
npm install -g worldmonitor # installs the `worldmonitor` command (alias: `wm`)
# or run ad-hoc without installing:
npx worldmonitor tools
tools lists every MCP tool and is public, so it's the fastest way to confirm the CLI reaches the API:
worldmonitor tools
You'll get all 63 tool definitions back as JSON. Everything else that returns data is a tools/call and needs a user API key.
Data commands map to MCP tools/call and require a user API key. Grab one at worldmonitor.app/pro, then either pass it per-call or export it once:
export WORLDMONITOR_API_KEY=wm_xxxxxxxx
worldmonitor risk IR # reads the key from the environment
# — or —
worldmonitor risk IR --api-key wm_xxxxxxxx # pass it explicitly
The key is sent as the X-WorldMonitor-Key header. See Authentication for how keys, OAuth, and browser sessions differ, and Rate Limits for the per-plan allowances. If you call a data command with no key, the CLI exits 1 and prints a hint telling you exactly which flag to pass.
Ergonomic shortcuts over the highest-traffic tools. Positional arguments (like an ISO country code) and any --key value pair flow straight through as tool arguments:
| Command | MCP tool | Notes |
|---|---|---|
world | get_world_brief | Live global situation brief |
country <ISO> | get_country_brief | AI strategic brief (ISO 3166-1 alpha-2) |
risk <ISO> | get_country_risk | Country risk / resilience scores |
markets | get_market_data | Equities, commodities, crypto, FX |
conflicts | get_conflict_events | --country, --min_fatalities, --limit |
cyber | get_cyber_threats | --min_severity, --threat_type, --country |
news | get_news_intelligence | --topic, --country, --alerts_only |
disasters | get_natural_disasters | --dataset, --active_only, --min_magnitude |
sanctions | get_sanctions_data | --country, --entity_type, --query |
forecasts | get_forecast_predictions | --domain, --region |
maritime <ISO> | get_maritime_activity | Port / vessel activity for a country |
worldmonitor country IR # AI strategic brief
worldmonitor conflicts --country IR --limit 5 # recent conflict events
worldmonitor markets --asset_class crypto # crypto quotes
The curated table stays small on purpose — every one of the 63 tools is reachable via call, and any unrecognised --key value becomes a tool argument, so nothing needs special wiring:
worldmonitor call get_cyber_threats --min_severity 7
worldmonitor call get_market_data --args '{"symbols":["AAPL","MSFT"]}' # typed JSON args
worldmonitor prompts # list pre-built workflow prompt templates
worldmonitor resources # list addressable resource URIs
Use --args '<json>' when you need typed (non-string) arguments; otherwise --key value pairs are collected as strings.
worldmonitor markets --jmespath 'data."stocks-bootstrap".quotes[?symbol==`AAPL`].{s:symbol,p:price}'
See the JMESPath guide for 12 worked examples. </Tip>
For host-relative paths, self-hosted deployments, or the OpenAPI catalog:
worldmonitor health --api-key wm_xxx # API status / health check (needs a key)
worldmonitor get /api/cyber/v1/list-cyber-threats --api-key wm_xxx
worldmonitor list cyber # list documented REST operations from the live spec
health maps to the auth-gated platform health endpoint, so it requires --api-key. list reads the public OpenAPI spec and needs no key.
| Flag | Purpose |
|---|---|
--api-key <key> | User API key (or env WORLDMONITOR_API_KEY) |
--mcp-url <url> | MCP endpoint (default https://worldmonitor.app/mcp) |
--base-url <url> | REST base (default https://api.worldmonitor.app) |
--args <json> | Typed arguments object for a tool call |
--timeout <ms> | Request timeout (default 30000) |
--raw | Print the response body verbatim |
--compact | Print single-line JSON |
-h, --help · -v, --version | Help / version |
| Code | Meaning |
|---|---|
0 | Success |
1 | Request or transport error (response body written to stderr) |
2 | Usage error (bad command or missing required argument) |
Predictable exit codes make the CLI safe to drive from shell pipelines and CI.
The same logic is importable — handy for embedding in a Node script without shelling out:
import { run } from 'worldmonitor/run';
const code = await run(['risk', 'IR'], { env: process.env });
run() takes an injectable IO bag (fetch, env, stdout, stderr), so it's fully testable offline, and returns the numeric exit code.
get and list commands.