@bloomai/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,67 +1,124 @@
 # Bloom CLI
 
-A command-line tool for accessing Bloom financial data. Designed for coding agents that need to download data to files and use bash tools (jq, grep, awk) to extract what they need, instead of loading everything into LLM context.
+Financial data CLI for coding agents. Downloads data to files so you can use bash (jq, grep, awk) to extract what you need instead of loading everything into context.
 
 ## Setup
 
 ```bash
-cd cli
-npm install
-npm run build
+npx @bloomai/cli --help
+# Or install globally:
+npm install -g @bloomai/cli
+
 export BLOOM_API_KEY=<your-key>
-node dist/index.js --help
+# Or: bloom auth login
 ```
 
-## Usage
+## Quick Research Workflow
 
 ```bash
-# Company fundamentals
-bloom info AAPL MSFT
-
-# Download to file for analysis
-bloom info AAPL -o /tmp/aapl.json
-jq '.symbols[0].basic_metadata | {name, latest_price, pe_ratio}' /tmp/aapl.json
+# 1. Find what you need
+bloom info AAPL                              # fundamentals, ratings, peers
+bloom info AAPL --fields basic_metadata,bottom_line_ratings  # specific sections only
 
-# Market data
-bloom sentiment
-bloom market --type top_movers
-bloom news AAPL --limit 5
+# 2. Download to files for analysis
+bloom info AAPL -o /tmp/bloom/aapl-info.json
+bloom news AAPL --limit 10 -o /tmp/bloom/aapl-news.json
+bloom price AAPL --timeframes 1m,1y -o /tmp/bloom/aapl-price.json
+bloom financials AAPL --type revenue -o /tmp/bloom/aapl-revenue.json
 
-# Screening
-bloom screen "market_cap > 100B" "pe_ratio < 25"
-
-# Analysis
-bloom earnings AAPL
-bloom technicals AAPL
-bloom catalysts AAPL
+# 3. Use bash to extract what matters
+jq '.symbols[0].basic_metadata | {name, latest_price, sector, pe_ratio}' /tmp/bloom/aapl-info.json
+jq '.articles[] | .headline' /tmp/bloom/aapl-news.json
+jq '.data[] | select(.revenue_growth > 0.1)' /tmp/bloom/aapl-revenue.json
 ```
 
-See [SKILL.md](./SKILL.md) for complete workflow patterns for coding agents.
-
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `info` | Company fundamentals, ratings, peers |
-| `news` | Recent news headlines |
-| `price` | Historical price data |
-| `financials` | Revenue, margins, cash flow |
-| `sentiment` | Market mood (AAII, Fear&Greed, VIX) |
-| `market` | Market map, sectors, movers |
-| `collections` | Curated stock lists |
-| `screen` | Filter stocks by metrics |
-| `earnings` | Earnings history & estimates |
-| `technicals` | RSI, MAs, patterns, options |
-| `options-history` | Options sentiment over time |
-| `portfolio` | Portfolio risk analysis |
-| `trades` | AI trade evaluation |
-| `catalysts` | Forward-looking value drivers |
-| `position-size` | Kelly criterion sizing |
-| `transcript` | Search earnings call transcripts |
+| Command | What it does | Example |
+|---------|-------------|---------|
+| `info` | Company fundamentals, ratings, peers | `bloom info AAPL MSFT` |
+| `news` | Recent news headlines | `bloom news AAPL --limit 5` |
+| `price` | Historical price data | `bloom price AAPL --timeframes 1d,1m,1y` |
+| `financials` | Revenue, margins, cash flow | `bloom financials AAPL --type revenue` |
+| `sentiment` | Market mood (AAII, Fear&Greed, VIX) | `bloom sentiment` |
+| `market` | Market map, sectors, movers | `bloom market --type top_movers` |
+| `collections` | Curated stock lists by theme | `bloom collections --section VALUE` |
+| `screen` | Filter stocks by metrics | `bloom screen "market_cap > 100B" "pe_ratio < 25"` |
+| `earnings` | Earnings history & estimates | `bloom earnings AAPL` |
+| `technicals` | RSI, MAs, patterns, options flow | `bloom technicals AAPL` |
+| `options-history` | Options sentiment over time | `bloom options-history AAPL --days 30` |
+| `portfolio` | Portfolio risk analysis | `bloom portfolio '{"AAPL":0.5,"MSFT":0.5}'` |
+| `trades` | AI trade evaluation | `bloom trades "Buy AAPL: strong AI catalysts"` |
+| `catalysts` | Forward-looking value drivers | `bloom catalysts AAPL MSFT` |
+| `position-size` | Kelly criterion sizing | `bloom position-size --bull 0.6 --bear -0.15 --conviction 8 --value 100000` |
+| `transcript` | Search earnings call transcripts | `bloom transcript AAPL "AI" "services"` |
 
 ## Global Flags
 
-- `-o, --output <file>` — write to file
-- `-f, --format json|csv|table` — output format
-- `-q, --quiet` — data only
+Every command supports:
+- `-o, --output <file>` — write to file instead of stdout
+- `-f, --format json|csv|table` — output format (default: json)
+- `-q, --quiet` — suppress headers, data only
 - `--raw` — raw API response
+
+## Common Patterns
+
+### Compare Multiple Stocks
+```bash
+mkdir -p /tmp/bloom/compare
+for ticker in AAPL MSFT GOOG AMZN; do
+  bloom info $ticker -o /tmp/bloom/compare/$ticker.json
+done
+# Extract key metrics
+for f in /tmp/bloom/compare/*.json; do
+  ticker=$(basename $f .json)
+  pe=$(jq -r '.symbols[0].basic_metadata.pe_ratio // "N/A"' $f)
+  price=$(jq -r '.symbols[0].basic_metadata.latest_price' $f)
+  echo "$ticker: \$$price (P/E: $pe)"
+done
+```
+
+### Screen → Deep Dive
+```bash
+# Find cheap large-caps
+bloom screen "market_cap > 50B" "pe_ratio < 20" "dividend_yield > 2" -o /tmp/bloom/screened.json
+
+# Get the tickers
+tickers=$(jq -r '.results[].symbol' /tmp/bloom/screened.json | head -5 | tr '\n' ' ')
+
+# Deep dive on each
+for t in $tickers; do
+  bloom earnings $t -o /tmp/bloom/earnings-$t.json
+  bloom catalysts $t -o /tmp/bloom/catalysts-$t.json
+done
+```
+
+### Market Check
+```bash
+bloom sentiment -o /tmp/bloom/sentiment.json
+bloom market --type major_indexes -o /tmp/bloom/indexes.json
+bloom market --type top_movers --limit 10 -o /tmp/bloom/movers.json
+
+# Quick summary
+jq '{fear_greed: .cnn_fear_greed.index_value, level: .cnn_fear_greed.level, vix: .volatility_analysis.assessment}' /tmp/bloom/sentiment.json
+```
+
+### Portfolio Review
+```bash
+bloom portfolio '{"AAPL":0.3,"MSFT":0.25,"GOOG":0.25,"AMZN":0.2}' --strategy "tech growth" -o /tmp/bloom/portfolio.json
+jq '.risk_metrics' /tmp/bloom/portfolio.json
+```
+
+### Earnings Research
+```bash
+bloom transcript AAPL "AI" "services" "margins" --max 20 -o /tmp/bloom/transcript.json
+jq '.matches[] | {speaker, text}' /tmp/bloom/transcript.json
+```
+
+## Tips
+
+- Use `-o` to download data to files, then `jq` to extract. Saves context tokens.
+- Batch multiple tickers: `bloom info AAPL MSFT GOOG` (up to 10).
+- Use `bloom screen` first to narrow your universe, then deep-dive with other commands.
+- `--fields` on `bloom info` reduces response size when you only need specific sections.
+- Pipe to `jq -r '.field'` for clean values usable in scripts.

package/SKILL.md

@@ -39,7 +39,7 @@ jq '.data[] | select(.revenue_growth > 0.1)' /tmp/bloom/aapl-revenue.json
 | `sentiment` | Market mood (AAII, Fear&Greed, VIX) | `bloom sentiment` |
 | `market` | Market map, sectors, movers | `bloom market --type top_movers` |
 | `collections` | Curated stock lists by theme | `bloom collections --section VALUE` |
-| `screen` | Filter stocks by metrics | `bloom screen "market_cap > 100B" "pe < 25"` |
+| `screen` | Filter stocks by metrics | `bloom screen "market_cap > 100B" "pe_ratio < 25"` |
 | `earnings` | Earnings history & estimates | `bloom earnings AAPL` |
 | `technicals` | RSI, MAs, patterns, options flow | `bloom technicals AAPL` |
 | `options-history` | Options sentiment over time | `bloom options-history AAPL --days 30` |
@@ -107,7 +107,7 @@ jq '.risk_metrics' /tmp/bloom/portfolio.json
 
 ### Earnings Research
 ```bash
-bloom transcript AAPL "AI" "services" "margins" --max-results 20 -o /tmp/bloom/transcript.json
+bloom transcript AAPL "AI" "services" "margins" --max 20 -o /tmp/bloom/transcript.json
 jq '.matches[] | {speaker, text}' /tmp/bloom/transcript.json
 ```
 

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@bloomai/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI tool for Bloom financial data - download market data to files for analysis",
   "type": "module",
   "bin": {
     "bloom": "./dist/index.js"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"
   },
-  "keywords": ["finance", "stocks", "cli", "bloom", "market-data"],
+  "keywords": [
+    "finance",
+    "stocks",
+    "cli",
+    "bloom",
+    "market-data"
+  ],
   "license": "MIT",
   "dependencies": {
     "cli-table3": "^0.6.5",

package/src/api.ts

@@ -1,67 +0,0 @@
-import { requireApiKey } from "./auth.js";
-
-const MCP_URL = "https://api.getbloom.app/mcp/";
-
-let requestId = 0;
-
-interface McpResponse {
-  jsonrpc: string;
-  id: number;
-  result?: {
-    content: Array<{ type: string; text: string }>;
-  };
-  error?: {
-    code: number;
-    message: string;
-  };
-}
-
-export async function callTool(
-  toolName: string,
-  args: Record<string, unknown>
-): Promise<unknown> {
-  const apiKey = requireApiKey();
-  requestId++;
-
-  const body = {
-    jsonrpc: "2.0",
-    method: "tools/call",
-    params: {
-      name: toolName,
-      arguments: args,
-    },
-    id: requestId,
-  };
-
-  const res = await fetch(MCP_URL, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`API error ${res.status}: ${text || res.statusText}`);
-  }
-
-  const data = (await res.json()) as McpResponse;
-
-  if (data.error) {
-    throw new Error(`MCP error ${data.error.code}: ${data.error.message}`);
-  }
-
-  if (!data.result?.content?.length) {
-    throw new Error("Empty response from API");
-  }
-
-  // The MCP response wraps the data as a JSON string inside content[0].text
-  const text = data.result.content[0].text;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}

package/src/auth.ts

@@ -1,83 +0,0 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-const CONFIG_DIR = join(homedir(), ".config", "bloom-cli");
-const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-
-interface Config {
-  api_key?: string;
-}
-
-function readConfig(): Config {
-  if (!existsSync(CONFIG_FILE)) return {};
-  try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-function writeConfig(config: Config): void {
-  try {
-    mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
-      mode: 0o600,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(
-      `Error: Could not write config to ${CONFIG_FILE}: ${msg}\n` +
-      `Try using BLOOM_API_KEY environment variable instead.`
-    );
-    process.exit(1);
-  }
-}
-
-export function getApiKey(): string | undefined {
-  return process.env.BLOOM_API_KEY || readConfig().api_key;
-}
-
-export function requireApiKey(): string {
-  const key = getApiKey();
-  if (!key) {
-    console.error(
-      "Error: No API key found. Set BLOOM_API_KEY or run: bloom auth login"
-    );
-    process.exit(1);
-  }
-  return key;
-}
-
-export function login(apiKey: string): void {
-  const config = readConfig();
-  config.api_key = apiKey;
-  writeConfig(config);
-  console.log("API key saved to " + CONFIG_FILE);
-}
-
-export function logout(): void {
-  if (existsSync(CONFIG_FILE)) {
-    const config = readConfig();
-    delete config.api_key;
-    writeConfig(config);
-  }
-  console.log("Logged out. API key cleared.");
-}
-
-export function status(): void {
-  const envKey = process.env.BLOOM_API_KEY;
-  const storedKey = readConfig().api_key;
-  if (envKey) {
-    console.log(`Authenticated via BLOOM_API_KEY (${maskKey(envKey)})`);
-  } else if (storedKey) {
-    console.log(`Authenticated via ${CONFIG_FILE} (${maskKey(storedKey)})`);
-  } else {
-    console.log("Not authenticated. Set BLOOM_API_KEY or run: bloom auth login");
-  }
-}
-
-function maskKey(key: string): string {
-  if (key.length <= 8) return "****";
-  return key.slice(0, 4) + "..." + key.slice(-4);
-}

package/src/commands/auth.ts

@@ -1,45 +0,0 @@
-import { Command } from "commander";
-import { login, logout, status } from "../auth.js";
-import { createInterface } from "node:readline";
-
-export function registerAuthCommand(program: Command): void {
-  const auth = program.command("auth").description("Manage API authentication");
-
-  auth
-    .command("login")
-    .description("Store API key")
-    .argument("[key]", "API key (or pass via stdin)")
-    .action(async (key?: string) => {
-      if (!key) {
-        const rl = createInterface({
-          input: process.stdin,
-          output: process.stderr,
-        });
-        key = await new Promise<string>((resolve) => {
-          rl.question("API key: ", (answer) => {
-            rl.close();
-            resolve(answer.trim());
-          });
-        });
-      }
-      if (!key) {
-        console.error("Error: No API key provided");
-        process.exit(1);
-      }
-      login(key);
-    });
-
-  auth
-    .command("status")
-    .description("Show current auth state")
-    .action(() => {
-      status();
-    });
-
-  auth
-    .command("logout")
-    .description("Clear stored credentials")
-    .action(() => {
-      logout();
-    });
-}

package/src/commands/catalysts.ts

@@ -1,18 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-export function registerCatalystsCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("catalysts")
-      .description("Forward-looking value catalysts")
-      .argument("<symbols...>", "Ticker symbols (up to 5)")
-  ).action(async (symbols: string[], opts: OutputOptions) => {
-    const data = await callTool("generate_catalysts", {
-      symbols: symbols.map((s) => s.toUpperCase()).slice(0, 5),
-    });
-    outputResult(data, opts);
-  });
-}

package/src/commands/collections.ts

@@ -1,20 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions, parseIntSafe } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-export function registerCollectionsCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("collections")
-      .description("Curated stock collections by theme")
-      .option("--section <s>", "GET_STARTED|VALUE|TRENDS|BEAT_UP|FAMOUS_INVESTORS|HIGH_FLYERS|SECTORS|GEO|LEADERBOARDS", "GET_STARTED")
-      .option("--limit <n>", "Max collections", "6")
-  ).action(async (opts: OutputOptions & { section: string; limit: string }) => {
-    const data = await callTool("get_collections", {
-      section: opts.section,
-      limit: parseIntSafe(opts.limit, 6),
-    });
-    outputResult(data, opts);
-  });
-}

package/src/commands/earnings.ts

@@ -1,18 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-export function registerEarningsCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("earnings")
-      .description("Earnings history, estimates, surprises")
-      .argument("<symbols...>", "Ticker symbols (up to 5)")
-  ).action(async (symbols: string[], opts: OutputOptions) => {
-    const data = await callTool("analyze_earnings", {
-      symbols: symbols.map((s) => s.toUpperCase()).slice(0, 5),
-    });
-    outputResult(data, opts);
-  });
-}

package/src/commands/financials.ts

@@ -1,30 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-const CHART_TYPES = [
-  "revenue",
-  "revenue_growth",
-  "operating_margin",
-  "net_earnings",
-  "net_earnings_growth",
-  "free_cash_flow",
-  "free_cash_flow_growth",
-];
-
-export function registerFinancialsCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("financials")
-      .description("Quarterly/annual financial data with YoY growth")
-      .argument("<symbol>", "Ticker symbol")
-      .option("--type <type>", "Chart type: " + CHART_TYPES.join(", "), "revenue")
-  ).action(async (symbol: string, opts: OutputOptions & { type: string }) => {
-    const data = await callTool("get_financial_charts", {
-      symbol: symbol.toUpperCase(),
-      chart_type: opts.type,
-    });
-    outputResult(data, opts);
-  });
-}

package/src/commands/info.ts

@@ -1,79 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-const VALID_FIELDS = [
-  "basic_metadata",
-  "bottom_line_ratings",
-  "embedded_expectations",
-  "peers",
-  "key_events",
-  "holdings",
-];
-
-export function registerInfoCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("info")
-      .description("Company fundamentals, ratings, peers, holdings")
-      .argument("<symbols...>", "Ticker symbols (e.g. AAPL MSFT)")
-      .option("--fields <fields>", "Comma-separated: " + VALID_FIELDS.join(","))
-  ).action(async (symbols: string[], opts: OutputOptions & { fields?: string }) => {
-    const args: Record<string, unknown> = {
-      symbols: symbols.map((s) => s.toUpperCase()),
-    };
-    if (opts.fields) {
-      args.fields = opts.fields.split(",").map((f) => f.trim());
-    }
-    const data = await callTool("get_symbols_metadata", args);
-    outputResult(data, opts, (d) => formatInfo(d));
-  });
-}
-
-function formatInfo(data: unknown): string {
-  if (!data || typeof data !== "object") return String(data);
-  const obj = data as Record<string, unknown>;
-  const sections: string[] = [];
-
-  for (const [key, val] of Object.entries(obj)) {
-    if (key === "timestamp" || key === "source") continue;
-    if (val && typeof val === "object") {
-      sections.push(`\n=== ${key.toUpperCase()} ===`);
-      sections.push(formatSection(val as Record<string, unknown>));
-    }
-  }
-
-  return sections.length > 0 ? sections.join("\n") : JSON.stringify(data, null, 2);
-}
-
-function formatSection(obj: Record<string, unknown>, indent = ""): string {
-  const lines: string[] = [];
-  for (const [k, v] of Object.entries(obj)) {
-    if (v && typeof v === "object" && !Array.isArray(v)) {
-      lines.push(`${indent}${k}:`);
-      lines.push(formatSection(v as Record<string, unknown>, indent + "  "));
-    } else if (Array.isArray(v)) {
-      if (v.length === 0) continue;
-      if (typeof v[0] === "string" || typeof v[0] === "number") {
-        lines.push(`${indent}${k}: ${v.join(", ")}`);
-      } else {
-        lines.push(`${indent}${k}:`);
-        for (const item of v) {
-          if (typeof item === "object" && item) {
-            const summary = Object.entries(item as Record<string, unknown>)
-              .slice(0, 4)
-              .map(([ik, iv]) => `${ik}=${iv}`)
-              .join("  ");
-            lines.push(`${indent}  - ${summary}`);
-          } else {
-            lines.push(`${indent}  - ${item}`);
-          }
-        }
-      }
-    } else {
-      lines.push(`${indent}${k}: ${v}`);
-    }
-  }
-  return lines.join("\n");
-}

package/src/commands/market.ts

@@ -1,22 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions, parseIntSafe } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-export function registerMarketCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("market")
-      .description("Market performance, sectors, global")
-      .option("--type <type>", "top_movers|sector_breakdown|global_markets|major_indexes", "top_movers")
-      .option("--period <p>", "1d|1w|1m|3m|6m|ytd|1y|5y", "1d")
-      .option("--limit <n>", "Max stocks for top_movers", "24")
-  ).action(async (opts: OutputOptions & { type: string; period: string; limit: string }) => {
-    const data = await callTool("get_market_map", {
-      map_type: opts.type,
-      period: opts.period,
-      limit: parseIntSafe(opts.limit, 24),
-    });
-    outputResult(data, opts);
-  });
-}

package/src/commands/news.ts

@@ -1,48 +0,0 @@
-import { Command } from "commander";
-import { callTool } from "../api.js";
-import { outputResult, OutputOptions, makeTable, parseIntSafe } from "../format.js";
-import { addGlobalOptions } from "../global-opts.js";
-
-export function registerNewsCommand(program: Command): void {
-  addGlobalOptions(
-    program
-      .command("news")
-      .description("Recent news from Benzinga channels")
-      .argument("<symbols...>", "Ticker symbols")
-      .option("--limit <n>", "Max articles (default: 15)", "15")
-  ).action(async (symbols: string[], opts: OutputOptions & { limit: string }) => {
-    const data = await callTool("get_news_for_symbols", {
-      symbols: symbols.map((s) => s.toUpperCase()),
-      limit: parseIntSafe(opts.limit, 15),
-    });
-    outputResult(data, opts, (d, o) => formatNews(d, o));
-  });
-}
-
-function formatNews(data: unknown, opts: OutputOptions): string {
-  if (!data || typeof data !== "object") return String(data);
-  const obj = data as Record<string, unknown>;
-
-  let articles: Record<string, unknown>[] = [];
-  if (Array.isArray(data)) {
-    articles = data as Record<string, unknown>[];
-  } else {
-    for (const val of Object.values(obj)) {
-      if (Array.isArray(val) && val.length > 0) {
-        articles = val as Record<string, unknown>[];
-        break;
-      }
-    }
-  }
-
-  if (articles.length === 0) return "(no articles)";
-
-  const rows = articles.map((a) => [
-    String(a.date || a.published || a.created || "").slice(0, 16),
-    String(a.title || a.headline || "").slice(0, 80),
-    String(a.symbols || a.tickers || a.stocks || "").slice(0, 20),
-    String(a.channel || a.source || ""),
-  ]);
-
-  return makeTable(["Date", "Title", "Symbols", "Channel"], rows, opts);
-}