@metisos/cascade-cli 0.1.0

package/dist/bin/cascade.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cascade.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const config_js_1 = require("../config.js");
+const status_js_1 = require("../commands/status.js");
+const entities_js_1 = require("../commands/entities.js");
+const events_js_1 = require("../commands/events.js");
+const prices_js_1 = require("../commands/prices.js");
+const chat_js_1 = require("../commands/chat.js");
+const portfolio_js_1 = require("../commands/portfolio.js");
+const graph_js_1 = require("../commands/graph.js");
+const skills_js_1 = require("../commands/skills.js");
+const config_js_2 = require("../commands/config.js");
+const program = new commander_1.Command();
+program
+    .name("cascade")
+    .description("Cascade CLI — Real-time geopolitical and economic intelligence")
+    .version("0.1.0");
+// Global format option
+function addFormat(cmd) {
+    return cmd.option("-f, --format <format>", "Output format: table, json, csv", (0, config_js_1.loadConfig)().output || "table");
+}
+// Status
+addFormat(program.command("status").description("System health, step, entity count")).action((opts) => (0, status_js_1.statusCommand)(opts).catch(handleError));
+// Entities
+addFormat(program.command("entities").description("List all entities with deviations")).action((opts) => (0, entities_js_1.entitiesCommand)(opts).catch(handleError));
+addFormat(program
+    .command("entity <name>")
+    .description("Entity detail + connections")
+    .option("--history", "Show deviation trajectory")
+    .option("--steps <n>", "History steps", "30")).action((name, opts) => (0, entities_js_1.entityCommand)(name, { ...opts, steps: parseInt(opts.steps) }).catch(handleError));
+addFormat(program.command("search <query>").description("Search entities")).action((query, opts) => (0, entities_js_1.searchCommand)(query, opts).catch(handleError));
+// Events
+addFormat(program
+    .command("events")
+    .description("Recent event feed")
+    .option("--limit <n>", "Number of events", "20")
+    .option("--type <type>", "Filter by event type")
+    .option("--watch", "Live streaming mode")).action((opts) => (0, events_js_1.eventsCommand)({ ...opts, limit: parseInt(opts.limit) }).catch(handleError));
+// Prices
+addFormat(program.command("prices").description("All tracked tickers")).action((opts) => (0, prices_js_1.pricesCommand)(opts).catch(handleError));
+addFormat(program
+    .command("price <entity>")
+    .description("Live price for an entity")
+    .option("--period <period>", "Price period: 1d, 5d, 1mo, 3mo", "5d")).action((entity, opts) => (0, prices_js_1.priceCommand)(entity, opts).catch(handleError));
+// Chat
+addFormat(program.command("chat <message>").description("Ask Cascade AI")).action((message, opts) => (0, chat_js_1.chatCommand)(message, opts).catch(handleError));
+// Dossier
+addFormat(program
+    .command("dossier")
+    .description("Generate intelligence report")
+    .requiredOption("--entities <list>", "Comma-separated entity names")
+    .option("--type <type>", "Report type", "strategic_assessment")).action((opts) => (0, chat_js_1.dossierCommand)(opts).catch(handleError));
+// Portfolio
+addFormat(program.command("portfolio").description("Portfolio entities with risk")).action((opts) => (0, portfolio_js_1.portfolioCommand)(opts).catch(handleError));
+// Graph
+addFormat(program.command("graph").description("Network node + edge counts")).action((opts) => (0, graph_js_1.graphCommand)(opts).catch(handleError));
+addFormat(program
+    .command("correlations")
+    .description("Pairwise correlation matrix")
+    .option("--dim <n>", "Dimension: 0=Stability, 1=Econ, 2=Political, 3=Social", "1")).action((opts) => (0, graph_js_1.correlationsCommand)({ ...opts, dim: parseInt(opts.dim) }).catch(handleError));
+addFormat(program
+    .command("lags")
+    .description("Lead/lag relationship matrix")
+    .option("--dim <n>", "Dimension", "1")).action((opts) => (0, graph_js_1.lagsCommand)({ ...opts, dim: parseInt(opts.dim) }).catch(handleError));
+// Skills
+program
+    .command("skills")
+    .description("Generate CASCADE_SKILLS.md for AI agents")
+    .option("--output <path>", "Write to file instead of stdout")
+    .option("--static", "Static output without live context")
+    .action((opts) => (0, skills_js_1.skillsCommand)(opts).catch(handleError));
+// Config
+program
+    .command("config <action> [key] [value]")
+    .description("Manage configuration (show, set, path)")
+    .action((action, key, value) => (0, config_js_2.configCommand)(action, key, value));
+// Error handler
+function handleError(err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+}
+// Parse
+program.parse();

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+export interface ApiResponse<T = unknown> {
+    data: T;
+    meta: {
+        step?: number;
+        timestamp: string;
+        org_id?: string;
+    };
+}
+export interface ApiError {
+    error: {
+        code: string;
+        message: string;
+        retry_after?: number;
+    };
+}
+export declare class CascadeClient {
+    private endpoint;
+    private apiKey;
+    constructor(endpoint?: string, apiKey?: string);
+    private request;
+    getState(): Promise<ApiResponse<Record<string, unknown>>>;
+    getEvents(limit?: number): Promise<ApiResponse<Record<string, unknown>>>;
+    getGraph(): Promise<ApiResponse<Record<string, unknown>>>;
+    getEntity(name: string): Promise<ApiResponse<Record<string, unknown>>>;
+    getEntityHistory(name: string, steps?: number): Promise<ApiResponse<Record<string, unknown>>>;
+    searchEntities(query: string): Promise<ApiResponse<unknown[]>>;
+    getPrices(): Promise<ApiResponse<Record<string, unknown>>>;
+    getPrice(entity: string, period?: string): Promise<ApiResponse<Record<string, unknown>>>;
+    getPortfolio(): Promise<ApiResponse<unknown[]>>;
+    getCorrelations(dim?: number): Promise<ApiResponse<Record<string, unknown>>>;
+    getLags(dim?: number): Promise<ApiResponse<Record<string, unknown>>>;
+    chat(message: string): Promise<ApiResponse<{
+        content: string;
+    }>>;
+    dossier(entities: string[], reportType?: string): Promise<ApiResponse<Record<string, unknown>>>;
+    pollSources(): Promise<ApiResponse<Record<string, unknown>>>;
+}

package/dist/client.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CascadeClient = void 0;
+const config_js_1 = require("./config.js");
+class CascadeClient {
+    endpoint;
+    apiKey;
+    constructor(endpoint, apiKey) {
+        const config = (0, config_js_1.loadConfig)();
+        this.endpoint = endpoint || config.endpoint;
+        this.apiKey = apiKey || config.api_key;
+        if (!this.apiKey) {
+            throw new Error("No API key configured. Run: cascade config set api-key <your-key>");
+        }
+    }
+    async request(path, opts = {}) {
+        const url = `${this.endpoint}/api/v1${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            ...opts.headers,
+        };
+        const res = await fetch(url, { ...opts, headers });
+        const body = await res.json();
+        if (!res.ok) {
+            const err = body;
+            const msg = err.error?.message || `HTTP ${res.status}`;
+            const code = err.error?.code || "unknown";
+            throw new Error(`[${code}] ${msg}`);
+        }
+        return body;
+    }
+    async getState() {
+        return this.request("/state");
+    }
+    async getEvents(limit = 20) {
+        return this.request(`/events?limit=${limit}`);
+    }
+    async getGraph() {
+        return this.request("/graph");
+    }
+    async getEntity(name) {
+        return this.request(`/entities/${encodeURIComponent(name)}`);
+    }
+    async getEntityHistory(name, steps = 30) {
+        return this.request(`/entities/${encodeURIComponent(name)}/history?steps=${steps}`);
+    }
+    async searchEntities(query) {
+        return this.request(`/entities/search?q=${encodeURIComponent(query)}`);
+    }
+    async getPrices() {
+        return this.request("/prices");
+    }
+    async getPrice(entity, period = "5d") {
+        return this.request(`/prices/${encodeURIComponent(entity)}?period=${period}`);
+    }
+    async getPortfolio() {
+        return this.request("/portfolio");
+    }
+    async getCorrelations(dim = 1) {
+        return this.request(`/calibration/correlations?dim=${dim}`);
+    }
+    async getLags(dim = 1) {
+        return this.request(`/calibration/lags?dim=${dim}`);
+    }
+    async chat(message) {
+        return this.request("/chat", {
+            method: "POST",
+            body: JSON.stringify({ message }),
+        });
+    }
+    async dossier(entities, reportType = "strategic_assessment") {
+        return this.request("/dossier", {
+            method: "POST",
+            body: JSON.stringify({ entities, report_type: reportType }),
+        });
+    }
+    async pollSources() {
+        return this.request("/sources/poll", {
+            method: "POST",
+            body: "{}",
+        });
+    }
+}
+exports.CascadeClient = CascadeClient;

package/dist/commands/chat.d.ts

@@ -0,0 +1,9 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function chatCommand(message: string, opts: {
+    format: OutputFormat;
+}): Promise<void>;
+export declare function dossierCommand(opts: {
+    format: OutputFormat;
+    entities: string;
+    type?: string;
+}): Promise<void>;

package/dist/commands/chat.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatCommand = chatCommand;
+exports.dossierCommand = dossierCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function chatCommand(message, opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.chat(message);
+    if (opts.format === "json") {
+        console.log((0, index_js_1.formatOutput)(data, "json"));
+        return;
+    }
+    console.log();
+    console.log(data.content);
+    console.log();
+}
+async function dossierCommand(opts) {
+    const entityList = opts.entities.split(",").map((e) => e.trim());
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.dossier(entityList, opts.type);
+    if (opts.format === "json") {
+        console.log((0, index_js_1.formatOutput)(data, "json"));
+        return;
+    }
+    const report = data;
+    console.log(`\n  ${report.title}`);
+    console.log(`  ${report.generated_at} | Step ${report.step} | ${report.system_health}\n`);
+    const sections = report.sections ?? [];
+    for (const s of sections) {
+        console.log(`  ${s.heading.toUpperCase()}`);
+        console.log(`  ${s.content}\n`);
+    }
+}

package/dist/commands/config.d.ts

@@ -0,0 +1 @@
+export declare function configCommand(action: string, key?: string, value?: string): void;

package/dist/commands/config.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configCommand = configCommand;
+const config_js_1 = require("../config.js");
+function configCommand(action, key, value) {
+    if (action === "show" || action === "list") {
+        const config = (0, config_js_1.loadConfig)();
+        console.log(`  Config: ${(0, config_js_1.getConfigPath)()}\n`);
+        console.log(`  api-key:   ${config.api_key ? config.api_key.slice(0, 16) + "..." : "(not set)"}`);
+        console.log(`  endpoint:  ${config.endpoint}`);
+        console.log(`  output:    ${config.output}`);
+        return;
+    }
+    if (action === "set" && key && value) {
+        const keyMap = {
+            "api-key": "api_key",
+            "apikey": "api_key",
+            "key": "api_key",
+            "endpoint": "endpoint",
+            "url": "endpoint",
+            "output": "output",
+            "format": "output",
+        };
+        const configKey = keyMap[key.toLowerCase()];
+        if (!configKey) {
+            console.error(`Unknown config key: ${key}`);
+            console.error(`Valid keys: api-key, endpoint, output`);
+            process.exit(1);
+        }
+        (0, config_js_1.saveConfig)({ [configKey]: value });
+        console.log(`  Set ${key} = ${configKey === "api_key" ? value.slice(0, 16) + "..." : value}`);
+        return;
+    }
+    if (action === "path") {
+        console.log((0, config_js_1.getConfigPath)());
+        return;
+    }
+    console.error("Usage: cascade config <show|set|path> [key] [value]");
+    process.exit(1);
+}

package/dist/commands/entities.d.ts

@@ -0,0 +1,12 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function entitiesCommand(opts: {
+    format: OutputFormat;
+}): Promise<void>;
+export declare function entityCommand(name: string, opts: {
+    format: OutputFormat;
+    history?: boolean;
+    steps?: number;
+}): Promise<void>;
+export declare function searchCommand(query: string, opts: {
+    format: OutputFormat;
+}): Promise<void>;

package/dist/commands/entities.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entitiesCommand = entitiesCommand;
+exports.entityCommand = entityCommand;
+exports.searchCommand = searchCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function entitiesCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getState();
+    const nodes = data.graph?.nodes ?? [];
+    const rows = nodes
+        .map((n) => {
+        const devs = n.deviation_pct ?? [];
+        const avg = devs.length > 0
+            ? devs.reduce((s, v) => s + Math.abs(v), 0) / devs.length
+            : 0;
+        return {
+            name: String(n.name).replace(/_/g, " "),
+            category: n.category,
+            deviation: `${avg.toFixed(1)}%`,
+            econ: devs[1] !== undefined ? `${devs[1] >= 0 ? "+" : ""}${devs[1].toFixed(1)}%` : "—",
+        };
+    })
+        .sort((a, b) => parseFloat(b.deviation) - parseFloat(a.deviation));
+    console.log((0, index_js_1.formatOutput)(rows, opts.format));
+}
+async function entityCommand(name, opts) {
+    const client = new client_js_1.CascadeClient();
+    if (opts.history) {
+        const { data } = await client.getEntityHistory(name, opts.steps ?? 30);
+        console.log((0, index_js_1.formatOutput)(data, opts.format));
+        return;
+    }
+    const { data } = await client.getEntity(name);
+    console.log((0, index_js_1.formatOutput)(data, opts.format));
+}
+async function searchCommand(query, opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.searchEntities(query);
+    console.log((0, index_js_1.formatOutput)(data, opts.format));
+}

package/dist/commands/events.d.ts

@@ -0,0 +1,7 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function eventsCommand(opts: {
+    format: OutputFormat;
+    limit?: number;
+    type?: string;
+    watch?: boolean;
+}): Promise<void>;

package/dist/commands/events.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventsCommand = eventsCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function eventsCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    if (opts.watch) {
+        console.log("Watching events (Ctrl+C to stop)...\n");
+        const seen = new Set();
+        const poll = async () => {
+            const { data } = await client.getEvents(opts.limit ?? 10);
+            const events = data.events ?? [];
+            for (const ev of events) {
+                const id = `${ev.timestamp ?? ev.time}-${ev.event_type ?? ev.type}-${ev.entity_name ?? ""}`;
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                const time = String(ev.timestamp ?? ev.time ?? "").slice(11, 19);
+                const sev = Math.round((ev.severity ?? 0) * 100);
+                const entity = String(ev.entity_name ?? (ev.entities ?? []).join(", "));
+                const evType = String(ev.event_type ?? ev.type ?? "").replace(/_/g, " ");
+                const sevLabel = sev >= 70 ? "CRITICAL" : sev >= 30 ? "WARNING" : "info";
+                console.log(`  ${time}  ${sevLabel.padEnd(8)}  ${evType.padEnd(22)}  ${entity}  (${sev}%)`);
+            }
+        };
+        await poll();
+        const interval = setInterval(poll, 5000);
+        process.on("SIGINT", () => { clearInterval(interval); process.exit(0); });
+        // Keep alive
+        await new Promise(() => { });
+        return;
+    }
+    const { data } = await client.getEvents(opts.limit ?? 20);
+    let events = data.events ?? [];
+    if (opts.type) {
+        events = events.filter((e) => String(e.event_type ?? e.type ?? "").toLowerCase().includes(opts.type.toLowerCase()));
+    }
+    const rows = events.map((e) => ({
+        time: String(e.timestamp ?? e.time ?? "").slice(11, 19),
+        type: (e.event_type ?? e.type ?? "").toString().replace(/_/g, " "),
+        entity: String(e.entity_name ?? (e.entities ?? []).join(", ")),
+        severity: `${Math.round((e.severity ?? 0) * 100)}%`,
+    }));
+    console.log((0, index_js_1.formatOutput)(rows, opts.format));
+}

package/dist/commands/graph.d.ts

@@ -0,0 +1,12 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function graphCommand(opts: {
+    format: OutputFormat;
+}): Promise<void>;
+export declare function correlationsCommand(opts: {
+    format: OutputFormat;
+    dim?: number;
+}): Promise<void>;
+export declare function lagsCommand(opts: {
+    format: OutputFormat;
+    dim?: number;
+}): Promise<void>;

package/dist/commands/graph.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graphCommand = graphCommand;
+exports.correlationsCommand = correlationsCommand;
+exports.lagsCommand = lagsCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function graphCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getGraph();
+    if (opts.format === "json") {
+        console.log((0, index_js_1.formatOutput)(data, "json"));
+        return;
+    }
+    const g = data;
+    console.log(`  Nodes: ${(g.nodes ?? []).length}`);
+    console.log(`  Edges: ${(g.edges ?? []).length}`);
+}
+async function correlationsCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getCorrelations(opts.dim ?? 1);
+    console.log((0, index_js_1.formatOutput)(data, opts.format));
+}
+async function lagsCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getLags(opts.dim ?? 1);
+    console.log((0, index_js_1.formatOutput)(data, opts.format));
+}

package/dist/commands/portfolio.d.ts

@@ -0,0 +1,4 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function portfolioCommand(opts: {
+    format: OutputFormat;
+}): Promise<void>;

package/dist/commands/portfolio.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.portfolioCommand = portfolioCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function portfolioCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getPortfolio();
+    console.log((0, index_js_1.formatOutput)(data, opts.format));
+}

package/dist/commands/prices.d.ts

@@ -0,0 +1,8 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function pricesCommand(opts: {
+    format: OutputFormat;
+}): Promise<void>;
+export declare function priceCommand(entity: string, opts: {
+    format: OutputFormat;
+    period?: string;
+}): Promise<void>;

package/dist/commands/prices.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pricesCommand = pricesCommand;
+exports.priceCommand = priceCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function pricesCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getPrices();
+    const tickers = data.tickers ?? [];
+    const rows = tickers.map((t) => ({
+        name: String(t.name).replace(/_/g, " "),
+        symbol: t.symbol,
+        category: t.category,
+    }));
+    console.log((0, index_js_1.formatOutput)(rows, opts.format));
+}
+async function priceCommand(entity, opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getPrice(entity, opts.period ?? "5d");
+    const bars = data.data ?? [];
+    if (opts.format === "json") {
+        console.log((0, index_js_1.formatOutput)(data, "json"));
+        return;
+    }
+    if (bars.length === 0) {
+        console.log("  No price data available");
+        return;
+    }
+    const last = bars[bars.length - 1];
+    const first = bars[0];
+    const change = last.close - first.close;
+    const changePct = (change / first.close) * 100;
+    console.log(`  ${String(data.entity).replace(/_/g, " ")}  (${data.symbol})`);
+    console.log(`  Price:   ${last.close.toFixed(2)}`);
+    console.log(`  Change:  ${change >= 0 ? "+" : ""}${change.toFixed(2)} (${changePct >= 0 ? "+" : ""}${changePct.toFixed(2)}%)`);
+    console.log(`  High:    ${last.high.toFixed(2)}`);
+    console.log(`  Low:     ${last.low.toFixed(2)}`);
+    console.log(`  Period:  ${bars.length} bars (${data.period})`);
+}

package/dist/commands/skills.d.ts

@@ -0,0 +1,4 @@
+export declare function skillsCommand(opts: {
+    output?: string;
+    static?: boolean;
+}): Promise<void>;

package/dist/commands/skills.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillsCommand = skillsCommand;
+const config_js_1 = require("../config.js");
+const fs_1 = __importDefault(require("fs"));
+async function skillsCommand(opts) {
+    const config = (0, config_js_1.loadConfig)();
+    const endpoint = config.endpoint || "https://cascade.metisos.co";
+    const content = generateSkillsFile(endpoint, opts.static);
+    if (opts.output) {
+        fs_1.default.writeFileSync(opts.output, content);
+        console.log(`Skills file written to ${opts.output}`);
+    }
+    else {
+        console.log(content);
+    }
+}
+function generateSkillsFile(endpoint, isStatic) {
+    return `# Cascade Intelligence — AI Agent Skills
+
+> These skills give you access to real-time geopolitical and economic
+> intelligence from the Cascade event propagation system.
+> Run commands via shell to query live data.
+> Endpoint: ${endpoint}
+
+## Setup
+
+Cascade CLI is configured and authenticated. Run commands directly.
+All commands support \`--format json\` for structured output.
+
+## Available Skills
+
+### Get System Status
+\`\`\`bash
+cascade status --format json
+\`\`\`
+Returns: system health (NOMINAL/WARNING/CRITICAL), simulation step,
+entity count, source status, peak impact.
+Use when: user asks about system state, health, or whether data is flowing.
+
+### List All Entities with Deviations
+\`\`\`bash
+cascade entities --format json
+\`\`\`
+Returns: all monitored entities with category, average deviation %, and
+economic deviation. Sorted by deviation (most impacted first).
+Use when: user asks "what's most impacted?", "show me the network", or
+wants an overview of all entities.
+
+### Get Entity Detail
+\`\`\`bash
+cascade entity <name> --format json
+\`\`\`
+Returns: current 4D deviation (Stability, Econ, Political, Social),
+category, connections, recent events affecting this entity.
+Use when: user asks about a specific country, sector, or asset.
+Example: \`cascade entity Crude_Oil --format json\`
+Note: entity names use underscores (e.g., United_States, Crude_Oil, SP500).
+
+### Get Entity Trajectory
+\`\`\`bash
+cascade entity <name> --history --steps 30 --format json
+\`\`\`
+Returns: historical deviation trajectory over N steps.
+Use when: user asks about trends, "is it getting worse?", recovery timing,
+or when a move started.
+
+### Search Entities
+\`\`\`bash
+cascade search "<query>" --format json
+\`\`\`
+Returns: matching entities by name, category, or tag.
+Use when: user mentions an entity but you're not sure of the exact name.
+
+### Get Live Prices
+\`\`\`bash
+cascade price <entity> --format json
+cascade prices --format json
+\`\`\`
+Returns: current market price, previous close, % change, recent history
+for tracked financial entities (stocks, indices, commodities, crypto).
+Use when: user asks about current prices, market levels, or price changes.
+Available tickers: SP500, DowJones, NASDAQ, FTSE100, Nikkei225, Crude_Oil,
+Gold, Bitcoin, VIX, US_10Y_Yield, US_Dollar, HangSeng.
+
+### Get Event Feed
+\`\`\`bash
+cascade events --limit 20 --format json
+cascade events --type "geopolitical_crisis" --format json
+\`\`\`
+Returns: recent events ingested from RSS, stock, and weather feeds.
+Use when: user asks "what happened?", "any recent events?", or wants
+to understand what's driving deviations.
+Event types: sanction, energy_shock, geopolitical_crisis, market_crash,
+stock_rise, stock_drop, policy_bundle, port_closure, pandemic.
+
+### Get Portfolio Risk
+\`\`\`bash
+cascade portfolio --format json
+\`\`\`
+Returns: portfolio entities with dollar-at-risk, risk scores, deviations.
+Use when: user asks about portfolio exposure or risk.
+
+### Get Correlation Data
+\`\`\`bash
+cascade correlations --format json
+cascade lags --format json
+\`\`\`
+Returns: pairwise correlation and lead/lag matrices between entities.
+Use when: user asks "how are X and Y related?", "what leads what?",
+or wants to understand co-movement patterns.
+
+### Get Network Graph
+\`\`\`bash
+cascade graph --format json
+\`\`\`
+Returns: full graph structure with all nodes and edges.
+Use when: user wants to understand the network topology or connection counts.
+
+### Ask Cascade AI
+\`\`\`bash
+cascade chat "your question here" --format json
+\`\`\`
+Ask the Cascade AI analyst about current geopolitical risks, entity
+analysis, portfolio impact, or any intelligence question. Has access
+to live simulation data, news search, and entity analysis tools.
+Use when: user needs analysis, interpretation, or forward-looking assessment
+rather than raw data.
+
+### Generate Intelligence Report
+\`\`\`bash
+cascade dossier --entities "Entity1,Entity2,Entity3" --format json
+\`\`\`
+Generates a multi-section intelligence briefing with live web sources.
+Use when: user asks for a report, briefing, or comprehensive analysis.
+
+### Watch Live Events
+\`\`\`bash
+cascade events --watch
+\`\`\`
+Streams new events as they arrive (polls every 5s). Ctrl+C to stop.
+Use when: user wants to monitor events in real-time.
+
+## When to Use Cascade
+
+- User asks about geopolitical risk, sanctions, market impact
+- User needs to understand how events cascade across economies/sectors
+- User asks about commodity prices, market correlations, portfolio risk
+- User wants to know which entities are most impacted right now
+- User asks about trends, recovery timing, or forward outlook
+- User needs an intelligence briefing on a region or sector
+- User asks "what's happening?" or "what's driving X?"
+
+## Entity Name Format
+
+Use underscores for multi-word names: \`United_States\`, \`Crude_Oil\`,
+\`Energy_Sector\`, \`Saudi_Arabia\`. Single-word names are plain: \`Iran\`,
+\`Gold\`, \`Bitcoin\`, \`VIX\`.
+
+## Output
+
+All commands support \`--format json\` for structured output that you
+can parse and reference in your responses. Always use \`--format json\`
+when calling these tools so you can extract specific values.
+`;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,4 @@
+import { type OutputFormat } from "../formatters/index.js";
+export declare function statusCommand(opts: {
+    format: OutputFormat;
+}): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const client_js_1 = require("../client.js");
+const index_js_1 = require("../formatters/index.js");
+async function statusCommand(opts) {
+    const client = new client_js_1.CascadeClient();
+    const { data } = await client.getState();
+    const nodes = data.graph?.nodes ?? [];
+    const summary = {
+        status: data.status ?? "active",
+        step: data.step,
+        entities: nodes.length,
+        health: getHealth(nodes),
+    };
+    if (opts.format === "json") {
+        console.log((0, index_js_1.formatOutput)(summary, "json"));
+    }
+    else {
+        console.log(`  CASCADE STATUS`);
+        console.log(`  Step:      ${summary.step}`);
+        console.log(`  Entities:  ${summary.entities}`);
+        console.log(`  Health:    ${summary.health}`);
+    }
+}
+function getHealth(nodes) {
+    let maxDev = 0;
+    for (const n of nodes) {
+        const devs = n.deviation_pct;
+        if (devs) {
+            const avg = devs.reduce((s, v) => s + Math.abs(v), 0) / devs.length;
+            if (avg > maxDev)
+                maxDev = avg;
+        }
+    }
+    return maxDev > 15 ? "CRITICAL" : maxDev > 8 ? "WARNING" : "NOMINAL";
+}

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface CascadeConfig {
+    api_key: string;
+    endpoint: string;
+    output: "table" | "json" | "csv";
+}
+export declare function loadConfig(): CascadeConfig;
+export declare function saveConfig(config: Partial<CascadeConfig>): void;
+export declare function getConfigPath(): string;

package/dist/config.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.getConfigPath = getConfigPath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), ".cascade");
+const CONFIG_FILE = path_1.default.join(CONFIG_DIR, "config.json");
+const DEFAULTS = {
+    api_key: "",
+    endpoint: "https://cascade.metisos.co",
+    output: "table",
+};
+function loadConfig() {
+    try {
+        if (fs_1.default.existsSync(CONFIG_FILE)) {
+            const raw = fs_1.default.readFileSync(CONFIG_FILE, "utf-8");
+            return { ...DEFAULTS, ...JSON.parse(raw) };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { ...DEFAULTS };
+}
+function saveConfig(config) {
+    const existing = loadConfig();
+    const merged = { ...existing, ...config };
+    if (!fs_1.default.existsSync(CONFIG_DIR)) {
+        fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + "\n");
+}
+function getConfigPath() {
+    return CONFIG_FILE;
+}

package/dist/formatters/index.d.ts

@@ -0,0 +1,2 @@
+export type OutputFormat = "table" | "json" | "csv";
+export declare function formatOutput(data: unknown, format: OutputFormat): string;

package/dist/formatters/index.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatOutput = formatOutput;
+function formatOutput(data, format) {
+    switch (format) {
+        case "json":
+            return JSON.stringify(data, null, 2);
+        case "csv":
+            return toCsv(data);
+        case "table":
+        default:
+            return toTable(data);
+    }
+}
+function toCsv(data) {
+    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object") {
+        const keys = Object.keys(data[0]);
+        const header = keys.join(",");
+        const rows = data.map((row) => {
+            const r = row;
+            return keys.map((k) => {
+                const v = r[k];
+                const s = v === null || v === undefined ? "" : String(v);
+                return s.includes(",") || s.includes('"') ? `"${s.replace(/"/g, '""')}"` : s;
+            }).join(",");
+        });
+        return [header, ...rows].join("\n");
+    }
+    return JSON.stringify(data);
+}
+function toTable(data) {
+    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object") {
+        const keys = Object.keys(data[0]);
+        const widths = keys.map((k) => Math.max(k.length, ...data.map((r) => {
+            const v = r[k];
+            return v === null || v === undefined ? 1 : String(v).length;
+        })));
+        const sep = widths.map((w) => "─".repeat(w + 2)).join("┼");
+        const header = keys
+            .map((k, i) => ` ${k.padEnd(widths[i])} `)
+            .join("│");
+        const rows = data.map((row) => {
+            const r = row;
+            return keys
+                .map((k, i) => {
+                const v = r[k];
+                const s = v === null || v === undefined ? "—" : String(v);
+                return ` ${s.padEnd(widths[i])} `;
+            })
+                .join("│");
+        });
+        return [header, sep, ...rows].join("\n");
+    }
+    if (typeof data === "object" && data !== null) {
+        const entries = Object.entries(data);
+        const maxKeyLen = Math.max(...entries.map(([k]) => k.length), 5);
+        return entries
+            .map(([k, v]) => {
+            const val = typeof v === "object" ? JSON.stringify(v) : String(v ?? "—");
+            return `  ${k.padEnd(maxKeyLen)}  ${val}`;
+        })
+            .join("\n");
+    }
+    return String(data);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@metisos/cascade-cli",
+  "version": "0.1.0",
+  "description": "Cascade CLI — Real-time geopolitical and economic intelligence from your terminal",
+  "bin": {
+    "cascade": "./dist/bin/cascade.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/bin/cascade.ts",
+    "start": "node dist/bin/cascade.js"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "ink": "^5.0.1",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}