@bloomai/cli 0.1.5 → 0.1.6

package/README.md

@@ -234,6 +234,7 @@ bloom sectors
 
 ## Tips
 
+- **Every command has `--help` with examples.** Run `bloom <command> --help` to see usage patterns, available options, and practical examples.
 - 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.

package/dist/index.js

@@ -376,7 +376,12 @@ function formatSection(obj, indent = "") {
 function registerNewsCommand(program2) {
   addGlobalOptions(
     program2.command("news").description("Recent news from Benzinga channels").argument("<symbols...>", "Ticker symbols").option("--limit <n>", "Max articles (default: 15)", "15")
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom news AAPL                  Latest Apple news
+  $ bloom news AAPL MSFT GOOGL       News for multiple stocks
+  $ bloom news TSLA --limit 5        Last 5 Tesla articles
+`).action(async (symbols, opts) => {
     const data = await callTool("get_news_for_symbols", {
       symbols: symbols.map((s) => s.toUpperCase()),
       limit: parseIntSafe(opts.limit, 15)
@@ -412,7 +417,13 @@ function formatNews(data, opts) {
 function registerPriceCommand(program2) {
   addGlobalOptions(
     program2.command("price").description("Historical price data").argument("<symbol>", "Ticker symbol").option("--timeframes <tf>", "Comma-separated: 1d,1w,1m,3m,6m,ytd,1y,2y,5y", "1d,1m,1y").option("--ohlc", "Include full OHLC data")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom price AAPL                        Default timeframes (1d, 1m, 1y)
+  $ bloom price TSLA --timeframes 1d,5y     Daily and 5-year price history
+  $ bloom price MSFT --ohlc                 Include open/high/low/close
+  $ bloom price AAPL -f csv -o prices.csv   Export to CSV file
+`).action(async (symbol, opts) => {
     const data = await callTool("get_price_charts", {
       symbol: symbol.toUpperCase(),
       timeframes: opts.timeframes.split(",").map((t) => t.trim()),
@@ -481,7 +492,13 @@ var CHART_TYPES = [
 function registerFinancialsCommand(program2) {
   addGlobalOptions(
     program2.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, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom financials AAPL                            Revenue (default)
+  $ bloom financials TSLA --type operating_margin     Operating margin trend
+  $ bloom financials MSFT --type free_cash_flow       Free cash flow history
+  $ bloom financials NVDA --type net_earnings_growth  Earnings growth rate
+`).action(async (symbol, opts) => {
     const data = await callTool("get_financial_charts", {
       symbol: symbol.toUpperCase(),
       chart_type: opts.type
@@ -500,7 +517,11 @@ var SECTIONS = [
 function registerSentimentCommand(program2) {
   addGlobalOptions(
     program2.command("sentiment").description("Market mood: AAII, Fear&Greed, VIX, momentum").option("--sections <s>", "Comma-separated: " + SECTIONS.join(","))
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom sentiment                                             All sentiment indicators
+  $ bloom sentiment --sections aaii_sentiment,cnn_fear_greed    Just AAII and Fear & Greed
+`).action(async (opts) => {
     const args = {};
     if (opts.sections) {
       args.sections = opts.sections.split(",").map((s) => s.trim());
@@ -536,7 +557,14 @@ function formatSentiment(data) {
 function registerMarketCommand(program2) {
   addGlobalOptions(
     program2.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").option("--universe <u>", "all|sp500|international|crypto|community", "all")
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom market                                   Today's top movers
+  $ bloom market --type sector_breakdown           Sector performance
+  $ bloom market --type global_markets             Global market overview
+  $ bloom market --type top_movers --period 1w     Weekly top movers
+  $ bloom market --universe sp500 --limit 10       Top 10 S&P 500 movers
+`).action(async (opts) => {
     const data = await callTool("get_market_map", {
       map_type: opts.type,
       period: opts.period,
@@ -551,7 +579,13 @@ function registerMarketCommand(program2) {
 function registerCollectionsCommand(program2) {
   addGlobalOptions(
     program2.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) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom collections                              Default collections
+  $ bloom collections --section VALUE              Value investing picks
+  $ bloom collections --section FAMOUS_INVESTORS   Famous investor portfolios
+  $ bloom collections --section TRENDS --limit 3   Top 3 trending collections
+`).action(async (opts) => {
     const data = await callTool("get_collections", {
       section: opts.section,
       limit: parseIntSafe(opts.limit, 6)
@@ -618,7 +652,11 @@ function formatScreen(data, opts) {
 function registerEarningsCommand(program2) {
   addGlobalOptions(
     program2.command("earnings").description("Earnings history, estimates, surprises").argument("<symbols...>", "Ticker symbols (up to 5)")
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom earnings AAPL              Apple earnings history and surprises
+  $ bloom earnings AAPL MSFT GOOGL   Compare earnings for multiple stocks
+`).action(async (symbols, opts) => {
     const data = await callTool("analyze_earnings", {
       symbols: symbols.map((s) => s.toUpperCase()).slice(0, 5)
     });
@@ -630,16 +668,24 @@ function registerEarningsCommand(program2) {
 function registerEarningsCalendarCommand(program2) {
   addGlobalOptions(
     program2.command("earnings-calendar").description(
-      "Upcoming earnings dates for symbols (default 28 days)"
-    ).argument("<symbols...>", "Ticker symbols").option("--days <n>", "Look-ahead window in days (1-90)", "28")
-  ).action(
+      "Upcoming earnings dates (all companies, or filter by symbols)"
+    ).argument("[symbols...]", "Ticker symbols (omit to show all)").option("--days <n>", "Look-ahead window in days (1-90)", "28")
+  ).addHelpText("after", `
+Examples:
+  $ bloom earnings-calendar AAPL MSFT GOOGL   Upcoming earnings for these stocks
+  $ bloom earnings-calendar TSLA --days 7     Earnings within the next week
+  $ bloom earnings-calendar NVDA --days 90    Earnings within 90 days
+`).action(
     async (symbols, opts) => {
       const days = parseIntSafe(opts.days, 28);
-      const syms = symbols.map((s) => s.toUpperCase()).join(",");
-      const data = await callRest("/markets/earnings-calendar/", {
-        symbols: syms,
-        days: String(days)
-      });
+      const params = { days: String(days) };
+      if (symbols.length > 0) {
+        params.symbols = symbols.map((s) => s.toUpperCase()).join(",");
+      }
+      const data = await callRest(
+        "/markets/earnings-calendar/",
+        params
+      );
       const items = data.results ?? [];
       outputResult(items, opts, (d, o) => {
         const rows = d;
@@ -665,7 +711,13 @@ var SECTIONS2 = ["technical_indicators", "options_analysis", "insider_activity"]
 function registerTechnicalsCommand(program2) {
   addGlobalOptions(
     program2.command("technicals").description("RSI, MAs, patterns, options flow, insider trades").argument("<symbols...>", "Ticker symbols (up to 5)").option("--sections <s>", "Comma-separated: " + SECTIONS2.join(","))
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom technicals AAPL                                 All technical data
+  $ bloom technicals TSLA --sections technical_indicators    RSI, MAs, patterns only
+  $ bloom technicals NVDA --sections options_analysis     Options flow only
+  $ bloom technicals AAPL --sections insider_activity     Insider trades only
+`).action(async (symbols, opts) => {
     const args = {
       symbols: symbols.map((s) => s.toUpperCase()).slice(0, 5)
     };
@@ -681,7 +733,13 @@ function registerTechnicalsCommand(program2) {
 function registerOptionsCommand(program2) {
   addGlobalOptions(
     program2.command("options-history").description("Options sentiment evolution over time").argument("<symbol>", "Ticker symbol").option("--days <n>", "Lookback days (7-90)", "30").option("--weekly", "Use weekly sampling (default)").option("--daily", "Use daily data").option("--greeks", "Include advanced Greeks analysis")
-  ).action(
+  ).addHelpText("after", `
+Examples:
+  $ bloom options-history AAPL              30-day options sentiment (default)
+  $ bloom options-history TSLA --days 90    90-day lookback
+  $ bloom options-history NVDA --daily      Daily granularity
+  $ bloom options-history AAPL --greeks     Include advanced Greeks analysis
+`).action(
     async (symbol, opts) => {
       const data = await callTool("analyze_options_history", {
         symbol: symbol.toUpperCase(),
@@ -717,7 +775,11 @@ function registerPortfolioCommand(program2) {
 function registerTradesCommand(program2) {
   addGlobalOptions(
     program2.command("trades").description("AI trade evaluation").argument("<trades...>", 'Trade descriptions: "Buy AAPL 30% because..." "Sell MSFT 20% because..."')
-  ).action(async (tradeStrs, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom trades "Buy AAPL 30% because of strong iPhone sales"
+  $ bloom trades "Sell MSFT 20% to take profits" "Buy GOOGL 15% on AI momentum"
+`).action(async (tradeStrs, opts) => {
     const trades = tradeStrs.map(parseTrade);
     const data = await callTool("analyze_trades", { trades });
     outputResult(data, opts);
@@ -750,7 +812,11 @@ Format: "Buy AAPL 30% because thesis" or JSON object`
 function registerCatalystsCommand(program2) {
   addGlobalOptions(
     program2.command("catalysts").description("Forward-looking value catalysts").argument("<symbols...>", "Ticker symbols (up to 5)")
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom catalysts AAPL              Upcoming catalysts for Apple
+  $ bloom catalysts TSLA NVDA AMZN    Catalysts for multiple stocks
+`).action(async (symbols, opts) => {
     const data = await callTool("generate_catalysts", {
       symbols: symbols.map((s) => s.toUpperCase()).slice(0, 5)
     });
@@ -896,7 +962,12 @@ function truncate2(s, max) {
 function registerAiPortfolioCommand(program2) {
   addGlobalOptions(
     program2.command("ai-portfolio").description("Current portfolio positions held by AI models (InvestingArena live accounts)").option("--model <m>", "Filter by AI model: claude|openai|gemini")
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom ai-portfolio                     All AI model portfolios
+  $ bloom ai-portfolio --model claude      Claude's current positions
+  $ bloom ai-portfolio --model openai      OpenAI's current positions
+`).action(async (opts) => {
     const args = {};
     if (opts.model) args.ai_model = opts.model;
     const data = await callTool("get_ai_trade_ideas", args);
@@ -1117,7 +1188,12 @@ function fmtNum(v) {
 function registerCorrelationCommand(program2) {
   addGlobalOptions(
     program2.command("correlation").description("Correlation matrix for a set of symbols").argument("<symbols...>", "Ticker symbols (2+)").option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)")
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom correlation AAPL MSFT GOOGL                                      Correlation matrix
+  $ bloom correlation AAPL TSLA --start 2025-01-01                         Since Jan 2025
+  $ bloom correlation SPY QQQ IWM --start 2024-01-01 --end 2024-12-31     Full year
+`).action(async (symbols, opts) => {
     const params = {
       symbols: symbols.map((s) => s.toUpperCase()).join(",")
     };
@@ -1143,7 +1219,11 @@ function formatCorrelation(data) {
 function registerRiskCommand(program2) {
   addGlobalOptions(
     program2.command("risk").description("Risk factors for a stock").argument("<symbol>", "Ticker symbol")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom risk AAPL       Risk factors for Apple
+  $ bloom risk TSLA       Risk factors for Tesla
+`).action(async (symbol, opts) => {
     const data = await callRest(`investments/${symbol.toUpperCase()}/risk_factors/`);
     outputResult(data, opts, formatRisk);
   });
@@ -1218,7 +1298,12 @@ function formatDrawdown(data) {
 function registerMacroCommand(program2) {
   addGlobalOptions(
     program2.command("macro").description("Macroeconomic indicators (GDP, CPI, unemployment, fed funds, treasury, inflation)").option("--indicators <list>", "Comma-separated: GDP,CPI,UNEMPLOYMENT,FED_FUNDS,TREASURY_10Y,INFLATION")
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom macro                                      All macro indicators
+  $ bloom macro --indicators GDP,CPI,UNEMPLOYMENT    Specific indicators only
+  $ bloom macro --indicators FED_FUNDS,TREASURY_10Y  Interest rates
+`).action(async (opts) => {
     const args = {};
     if (opts.indicators) {
       args.indicators = opts.indicators;
@@ -1255,7 +1340,11 @@ function formatMacro(data) {
 function registerSectorsCommand(program2) {
   addGlobalOptions(
     program2.command("sectors").description("Sector performance across time periods")
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom sectors           Sector performance across all time periods
+  $ bloom sectors -f json   Output as JSON
+`).action(async (opts) => {
     const data = await callTool("get_sector_performance", {});
     outputResult(data, opts, formatSectors);
   });
@@ -1309,7 +1398,11 @@ function formatSectors(data) {
 function registerDcfCommand(program2) {
   addGlobalOptions(
     program2.command("dcf").description("Discounted cash flow valuation").argument("<symbol>", "Ticker symbol")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom dcf AAPL   Discounted cash flow valuation for Apple
+  $ bloom dcf TSLA   DCF valuation for Tesla
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const result = await callTool("get_dcf_valuation", { symbol: sym });
     outputResult(result, opts, () => formatDcf(result, sym));
@@ -1336,7 +1429,12 @@ function formatDcf(data, symbol) {
 function registerHoldersCommand(program2) {
   addGlobalOptions(
     program2.command("holders").description("Institutional and mutual fund holders").argument("<symbol>", "Ticker symbol").option("--type <t>", "institutional or mutual-fund (default: both)").option("--limit <n>", "Max holders to show", "15")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom holders AAPL                         All holders (institutional + mutual fund)
+  $ bloom holders TSLA --type institutional    Institutional holders only
+  $ bloom holders NVDA --limit 5               Top 5 holders
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const limit = parseIntSafe(opts.limit, 15);
     const args = { symbol: sym };
@@ -1378,7 +1476,11 @@ function fmtNum2(v) {
 function registerShortInterestCommand(program2) {
   addGlobalOptions(
     program2.command("short-interest").description("Short interest history").argument("<symbol>", "Ticker symbol").option("--limit <n>", "Number of records", "10")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom short-interest GME              Short interest history for GameStop
+  $ bloom short-interest AMC --limit 20   Last 20 short interest records
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const limit = parseIntSafe(opts.limit, 10);
     const data = await callTool("get_short_interest", { symbol: sym, limit });
@@ -1411,7 +1513,11 @@ function fmtNum3(v) {
 function registerInsiderCommand(program2) {
   addGlobalOptions(
     program2.command("insider").description("Insider trading activity (SEC Form 4)").argument("<symbol>", "Ticker symbol").option("--limit <n>", "Max transactions to show", "20")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom insider AAPL              Recent insider trades for Apple
+  $ bloom insider TSLA --limit 5    Last 5 insider transactions
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const limit = parseIntSafe(opts.limit, 20);
     const data = await callTool("get_insider_trading", { symbol: sym, limit });
@@ -1445,7 +1551,12 @@ function fmtNum4(v) {
 function registerDividendsCommand(program2) {
   addGlobalOptions(
     program2.command("dividends").description("Dividend history for a stock").argument("<symbol>", "Ticker symbol").option("--limit <n>", "Number of records", "20").option("--from <date>", "Start date (YYYY-MM-DD)")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom dividends KO                       Dividend history for Coca-Cola
+  $ bloom dividends AAPL --limit 8           Last 8 dividends
+  $ bloom dividends JNJ --from 2024-01-01    Dividends since Jan 2024
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const limit = parseIntSafe(opts.limit, 20);
     const args = { symbol: sym, limit };
@@ -1471,7 +1582,11 @@ function formatDividends(data) {
 function registerSplitsCommand(program2) {
   addGlobalOptions(
     program2.command("splits").description("Stock split history").argument("<symbol>", "Ticker symbol").option("--from <date>", "Start date (YYYY-MM-DD)")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom splits AAPL                    Stock split history for Apple
+  $ bloom splits TSLA --from 2020-01-01  Splits since 2020
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const args = { symbol: sym };
     if (opts.from) args.from_date = opts.from;
@@ -1492,7 +1607,11 @@ function formatSplits(data) {
 function registerIpoCommand(program2) {
   addGlobalOptions(
     program2.command("ipo").description("Upcoming and recent IPOs").option("--from <date>", "Start date (YYYY-MM-DD)").option("--to <date>", "End date (YYYY-MM-DD)")
-  ).action(async (opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom ipo                                            Recent and upcoming IPOs
+  $ bloom ipo --from 2025-01-01 --to 2025-06-30          IPOs in H1 2025
+`).action(async (opts) => {
     const args = {};
     if (opts.from) args.from_date = opts.from;
     if (opts.to) args.to_date = opts.to;
@@ -1525,7 +1644,12 @@ function fmtNum5(v) {
 function registerCompareCommand(program2) {
   addGlobalOptions(
     program2.command("compare").description("Side-by-side comparison of stocks").argument("<symbols...>", "Ticker symbols (2-10)")
-  ).action(async (symbols, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom compare AAPL MSFT            Side-by-side comparison
+  $ bloom compare AAPL MSFT GOOGL AMZN Compare big tech stocks
+  $ bloom compare TSLA RIVN LCID       Compare EV manufacturers
+`).action(async (symbols, opts) => {
     const syms = symbols.map((s) => s.toUpperCase()).slice(0, 10);
     const data = await callTool("get_symbols_metadata", { symbols: syms });
     outputResult(data, opts, (d) => formatComparison(d, syms));
@@ -1582,7 +1706,11 @@ function fmtCap(v) {
 function registerRatingsCommand(program2) {
   addGlobalOptions(
     program2.command("ratings").description("Analyst ratings, grades, and price targets").argument("<symbol>", "Ticker symbol").option("--limit <n>", "Max records to show", "20")
-  ).action(async (symbol, opts) => {
+  ).addHelpText("after", `
+Examples:
+  $ bloom ratings AAPL              Analyst ratings and price targets
+  $ bloom ratings NVDA --limit 5    Last 5 analyst actions
+`).action(async (symbol, opts) => {
     const sym = symbol.toUpperCase();
     const limit = parseIntSafe(opts.limit, 20);
     const result = await callTool("get_analyst_ratings", { symbol: sym, limit });
@@ -1629,7 +1757,7 @@ function fmtNum6(v) {
 var program = new Command();
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
 var pkgPath = path.join(__dirname, "..", "package.json");
-var compiledVersion = "0.1.5".length > 0 ? "0.1.5" : void 0;
+var compiledVersion = "0.1.6".length > 0 ? "0.1.6" : void 0;
 var envVersion = process.env.BLOOM_CLI_VERSION ?? process.env.npm_package_version;
 var fallbackVersion = compiledVersion ?? "unknown";
 var cliVersion = envVersion ?? fallbackVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloomai/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "CLI tool for Bloom financial data - download market data to files for analysis",
   "type": "module",
   "bin": {