# User guide [Back to README](../README.md) · [Installation](installation.md) · [Browser app](browser.md) - [Research data conventions](research-data.md) - [Financial ratios](financial-ratios.md) - [Options positioning (OPX)](options-positioning.md) - [Keyboard shortcuts](#keyboard) - [Command reference and chart composer](#command-reference) - [Live prices and refresh cadence](#live-prices-and-refresh-cadence) - [CLI commands and output formats](#cli) - [Plugins pane](#plugins-pane) - [Portfolio currency](#portfolio-currency) - [Dividend income and DRIP](#dividend-income-and-drip) - [Importing a manager's 13F as a portfolio](#importing-a-managers-13f-as-a-portfolio) - [Cash, target weights and rebalancing](#cash-target-weights-and-rebalancing) - [Broker position sync](#broker-position-sync) - [Gloom Cloud sign-in](#gloom-cloud-sign-in) - [Connect an AI assistant (MCP)](#connect-an-ai-assistant-mcp) - [Debt maturities](#debt-maturities) - [Theses](#theses) - [Interface language](#localized-interface) - [Built-in plugins](#built-in-plugins) - [Live TV](#live-tv) - [Options scenarios](#options-scenarios) - [Option valuation models](#option-valuation-models) - [Relative rotation](#relative-rotation) - [Position sizing: KELLY](#position-sizing-kelly) - [Portfolio risk: PORT and MARS](#portfolio-risk-depth-port-and-mars) - [Equity criteria screener](#equity-criteria-screener) - [Backtest](#backtest) The desktop app and TUI share the command language and plugin system. The [browser app](browser.md) offers a smaller feature set. Use `HELP` in the app or `gloom help` in your shell for the commands available in your installation. ## Keyboard | Key | Action | |-----|--------| | `Ctrl+P` | Open command mode | | `` ` `` | Open ticker search | | `.` | Open the focused pane's menu (also `Shift+F10` or the Menu key) | | `Ctrl+,` | Open focused pane settings | | `Ctrl+W` | Close focused pane (unless it is locked) | | `Ctrl+Shift+M` | Move focused window (`WIN resize` starts resize mode) | | `Ctrl+Shift+D` | Dock or float focused pane | | `Ctrl+Shift+N` | Move the focused pane to a new layout of its own; again to move it back | | `Ctrl+Shift+E` | Export focused pane table as CSV | | `Cmd/Ctrl+Shift+S` | Share the focused pane: post to chat or copy link | | `Ctrl+Shift+L` | Layout actions | | `Ctrl+Shift+G` | Tidy windows | | `Alt+A` | Ask Gloom about the focused pane, in a new conversation with the pane attached | | `Tab` | Switch panes | | `j` / `k` | Navigate lists | | `Home` / `End`, `PageUp` / `PageDown` | Jump through lists and tables | | `Enter` / `Esc` | Open the selected row / go back | | `/` | Search in the focused pane | | `h` / `l` | Switch tabs | | `<` / `>` | Narrow or widen a pane's sidebar, such as the list beside the map (the divider also drags) | | `Ctrl+Left` / `Ctrl+Right` | Scroll a focused table horizontally | | `m` | Cycle chart mode | | `Alt+Enter` | Run the newest notification's action, such as Revert or Review | | `Alt+Backspace` | Dismiss the newest notification | | `q` | Quit (terminal) | Desktop builds add the matching `Cmd` shortcuts on macOS and these: | Key | Action | |-----|--------| | `Cmd/Ctrl+K` | Open the command bar | | `Cmd/Ctrl+Shift+O` | Pop out a pane | | `Cmd/Ctrl+Shift+C` | Copy a screenshot of the focused pane | | `Cmd/Ctrl+Shift+A` | Ask Gloom about the focused pane | | `Cmd/Ctrl+Shift+Enter` / `Cmd/Ctrl+Shift+Backspace` | Run / dismiss the newest notification's action | ### Footer and pane menu The focused pane's footer shows its actions with their keys, such as `[a]dd`. The pane menu (`.` or the `...` button) lists every action, then the pane's table, filters, tabs and toggles, then the pane and window actions. ### Dialogs and forms - Dialogs: `Enter` confirms, `Esc` closes (on the desktop `Tab` moves between controls). - Forms: `Tab` and the arrows move between fields, `Enter` goes to the next field and sends from the last, `Cmd/Ctrl+S` sends from any field, `y` or `n` answers a confirm. - Pane settings: the arrows move between settings, `Left` / `Right` change a choice in place, `Enter` opens a field's editor. ### Linking a pane to a list A pane that shows one ticker (`GP`, `GIP`, `OMON`, `OPX`, `SEAS`, `FA`, company news) can follow a watchlist, portfolio or scanner like the research pane. Choose **Link to** and the list's name in its pane menu (`OPX NVDA ⧉ Linked to Watchlist`). - It can also follow another single-ticker pane (**Link to Ticker Research AAPL**), so a desk of option panes moves with one research pane. - **Unlink from** keeps the ticker the pane shows. If the list was empty, a linked `OMON`, `CN`, `FA`, `HP`, `SEC`, `INS`, `HDS`, `ANR`, `EVT` or `EE` pane has no ticker to keep and closes. - Typing `OPX AAPL` while a linked OPX is open opens a separate pane. ### Move to New Layout Takes the focused pane out of its layout into a new layout tab named after it (`Chart: NVDA`), where it fills the window. Use `Ctrl+Shift+N` (`Cmd+Shift+N` in the macOS desktop app), the pane menu or the command bar. In the browser `Ctrl+Shift+N` opens a private window, so use the pane menu. **Move Back to** in the pane menu, or the same shortcut while the pane is alone, returns it to its place and removes the empty layout (if that layout was deleted, the pane docks in the first other tab). The pane keeps its ticker, tab, settings and lock. ### Resizing Drag the line between docked panes, or a floating pane's bottom-right corner (any edge or corner on the desktop and web). ### Docs inside the app The `?` beside a pane's `...` opens that pane's entry in `DOCS`: the gloom.sh docs and Academy lessons, with what the function is, an example and the lesson that teaches it. Docs read offline from the copy the app ships. - `DOCS` alone searches every function, page and lesson. `DOCS OMON` opens one entry. - `Esc` goes back, `o` opens the page on gloom.sh, `F1` opens the focused pane's help card and `Enter` reads its docs. In a popped-out desktop window the `?` shows the help card. ```bash gloom fn DOCS OMON # the whole page, wrapped to the terminal gloom fn DOCS # the index, cut at the first screen (it says so) ``` A name with no entry fails with `No docs entry for zzzz.` and points at `gloom fn DOCS`. Wide tables keep their columns in narrow panes. Use the horizontal scrollbar or wheel, or `Ctrl+Left` / `Ctrl+Right`. In the terminal, a header that ends in `more →` has columns past its right edge, and a click on it moves right. With no room for the words it reads `more` or `→`; it never hides a column. ### Custom keybindings Every global and pane management key can be moved, and any command bar text can be put on a key. - `HELP` > Shortcuts: press Enter on a row (or double-click) to capture the next chord. `x` unbinds, `0` restores the default, `N` starts a command binding. Typing a command such as `DES AAPL` in the command bar also offers a `Bind a key` row. - Where the backtick is a dead key, type after `Ctrl+P` to search symbols, or rebind ticker search. The table lives in `config.json` and the CLI: ```bash gloom config get keybindings gloom config set keybindings.actions.ticker-search "Ctrl+T" gloom config set keybindings.actions.help null gloom config set keybindings.actions.ticker-search default gloom config set keybindings.commands.Alt+1 "DES AAPL" ``` ```json "keybindings": { "actions": { "ticker-search": "Ctrl+T", "command-bar": ["Ctrl+Shift+P", "CmdOrCtrl+K"], "help": null }, "commands": { "Alt+1": "DES AAPL", "F5": "CN" } } ``` Chords use `Ctrl`, `Cmd`, `Alt`, `Shift` and `CmdOrCtrl` (Control in the terminal, Command on a Mac desktop), then a key (`K`, `,`, `` ` ``, `Tab`, `F5`). - Action ids are listed by `gloom config get keybindings`. Plugin shortcuts use `plugin:`. - A command binding runs its text as typed and needs a modifier or a function key. Control chords yield to a focused text field. - Bindings are per machine and not synced. A binding that does not parse or lands on a taken key is reported at launch and in Help > Shortcuts. ## Command Reference Use `HELP` inside Gloom for the live shortcut list. The common command-bar prefixes are listed here. The command bar leads with **Start Here** (common first tasks in plain words, each with its code) for its first ten opens, and Help's Basics tab starts with **Try These** (`DES AAPL`, `GP NVDA`, `CMP AAPL MSFT`). ### Searching by asset class Text that no command claims searches symbols and names. Every result carries its class: | Class | Means | |-------|-------| | `EQ` | Equity (receipts, preferred shares and partnership units included) | | `ETF` | Exchange-traded fund | | `FUND` | Any other fund (mutual, closed-end or money-market) | | `CUR` | Currency pair | | `CRYP` | Coin | | `FUT` | Future | | `IDX` | Index | | `OPT` | Option | | `DERIV` | Other derivatives | End a search with one of those codes, other than `DERIV`, to keep only that class, in ticker search (`` ` ``) and after `DES`: `ES FUT` finds the E-mini S&P 500 future rather than Eversource, and `EURUSD CUR`, `BTC CRYP`, `SPY ETF`, `S&P 500 IDX` work the same (`AAPL OPT` lists contracts when a connected broker returns them). - `CUR` keeps coins as well (`BTC CUR`), and `FUND` keeps exchange-traded funds as well. - For `FUT`, `CUR`, `CRYP` and `IDX`, a bare symbol is also looked up in its market spelling (`ES=F`, `EURUSD=X`, `BTC-USD`, `^GSPC`). - A code on its own, or first, is not a filter: `EQ` searches that symbol, and `FUT`, `CRYP` and `ETF SPY` open their panes. A symbol that trades in several places lists its exchanges after a colon. `NET:` shows each one, your saved listing first, and a symbol several companies use lists them all (`CAR:` offers CAR Group on ASX as well as Avis and Carrefour). Letters after the colon narrow the list (`NET:L`), and `NET:XLON` names one listing. Enter on a typed symbol or ticker command uses the standard listing resolution (`DES HFC` opens the former US listing and shows its move to DINO, as `quote HFC` does). To choose another listing, use the arrow keys or click a search row. A saved symbol keeps its saved listing. When Gloom Cloud is too busy to search, the list says `Search is busy` rather than `No matches`, and saved tickers that match still show. `gloom search` and any command that looks a symbol up through search (`quote "Eagle Bulk"`, `watchlist add`) fails with `Search is busy, try again in a moment.` and exits 1 (`--json`: `code` `search_busy`, `retryable` `true`). ### Company Research | Shortcut | Function | |----------|----------| | `DES ` / `T ` | Security details for a ticker | | `FA ` | Financial statements and [ratio tabs](financial-ratios.md) | | `SEG ` | Quarterly revenue by product, segment or region from 10-Q and 10-K filings | | `G ` | Custom chart composer | | `CAT [query]` | Browse and search chartable series | | `GP ` | Price chart | | `GIP ` | Intraday price chart | | `HP ` | Historical OHLCV prices, daily bars over 3M to start. The range sets the bar size (5Y weekly, ALL monthly) and the newest bar reads `DTD`, `WTD` or `MTD` while it runs | | `GF ` | Fundamental statement graph | | `GE ` | Valuation multiple graph | | `GR ` | Ratio, rolling correlation and regression of two tickers (`GR GC=F SI=F`) | | `EE ` | Events view with earnings and revenue estimates | | `ERN [tickers]` | Earnings history with implied and realized moves. Several tickers, their upcoming reports. Nothing active, the market's report days | | `EVTS [ticker]` | The market's report days with implied and average moves, and each report's actual, surprise and move so far | | `SRCH [query]` | Full-text search across earnings call transcripts, news, and SEC filings | | `CALLS [ticker]` | Earnings calls and their transcripts; alone, the calendar of every company's calls | | `JOBS [ticker]` | Hiring from the company's careers system; alone, every covered company | | `QQ ` | Ticker quote monitor | | `CMP ` | Normalized price comparison (`fn CMP LMT RTX --range YTD`). A leveraged or inverse fund adds its daily objective and decay, see [Leveraged and inverse funds](#leveraged-and-inverse-funds) | | `CORR ` | Return correlations; `GEO:` adds a map series (`CORR FRO, STNG, GEO:HORMUZ`) | | `ANR ` | Analyst targets and ratings | | `DIAG ` | Equity Diagnostic with cited flags and anomalies | | `SEC ` | SEC filings and company disclosures | | `OMON ` | Options chain, expected moves, 25-delta skew and term slope. **Strikes** in the bar lists every strike, a count either side of the money, or a delta band ([method](research-data.md#omon-strike-window-and-carry)) | | `OVDV ` | Rotatable 3D implied-volatility surface by delta or moneyness, smiles, term structure, skew and forwards | | `OPX [ticker]` / `GEX [ticker]` | Open interest by strike and expiry with max pain, and dealer gamma with its flip level and walls. `GEX` opens on the gamma tab, `MAXPAIN` is `OPX`. SPY with no ticker ([method](options-positioning.md)) | | `HVG ` | Realized volatility by estimator and window, price, and current ATM IV | | `HVT ` | Volatility cone, current estimates and historical percentiles | | `SEAS ` | Seasonality: monthly returns by year, average and hit rate, year overlays, weekday and turn-of-month returns | | `RIPL [tickers]` | Earnings Ripple: customers and suppliers of your holdings (or the named tickers) reporting in the next 30 days, with the disclosed revenue share. Pro adds companies two hops away | | `ADR ` | A depositary receipt beside its home listing (GGAL and GGAL.BA, TSM and 2330.TW): the ratio, both prices with their times, the implied dollar rate (home × ratio / ADR, the CCL rate for an Argentine pair), spot and the premium or discount. Opens DES on its ADR vs Home tab, which shows for listings with a known pair | | `RDCF ` | Reverse DCF: the ten-year free cash flow growth the enterprise value prices in, against past growth, by discount rate | | `PEB ` | P/E band: weekly price against round multiples of trailing EPS, today's P/E and its percentile | | `MDAY ` | Macro-day reaction: average absolute and signed move and up share on CPI, jobs, FOMC and Brazil IPCA days against a normal day, with each day's actual, forecast and prior | | `HIVG ` | Implied volatility history against realized, with IV rank and percentile | | `VCA [tickers]` | Rich/cheap implied volatility across a list: IV rank, percentile, term slope, skew, IV/HV | | `OSA ` | Multi-leg option positions, scenario P&L, payoff charts and aggregate Greeks, with a hedge budget, a collar or a cash-secured put | | `CSP ` | Cash-secured puts across a list, ranked by annualised yield at the bid | | `OVME` | Option calculator: European Black-Scholes or American pricing, discrete dividends, Greeks, implied and surface volatility | | `HDS ` | Institutional holders, and 13D/13G beneficial owners over 5% | | `DVD ` | Dividend yield and history; several tickers rank in one table by yield | | `SI ` | Short interest | | `SIV ` | FINRA daily off-exchange short-volume ratio, history and percentile | | `SIW [tickers]` | Short squeeze watch across your portfolios and watchlists: short interest as a share of float, days to cover, change since the prior settlement and the 1M move | | `BUZZ ` | Daily posts on X naming the cashtag, the 30-day median, top posts and their stance | | `13F [fund/ticker/CIK]` | 13F fund filings and holdings | | `INS [ticker]` | Insider activity. Alone, the companies whose insiders are buying or selling in the open market | | `EVT ` | Corporate actions, earnings, and estimates | | `RV ` | Relative valuation | #### Company function notes - **`GR`:** beta and alpha regress the first ticker's daily returns on the second's and say so (`EQT on UNG: beta`). Text prints the rolling correlation to three decimals, `--json` and `--csv` keep every digit. - **`ERN`:** the bar's Range looks back or ahead, as in `EVTS`. With Mine the market's report days narrow to the names in your portfolios and watchlists. - **`EVTS`:** a ticker selects its row and its report says whether it is on the board (`ERN ` has its own dates). The bar's Range gives a week (`gloom fn EVTS --week last`, `this` or `next`), or one day (`--date 2026-10-15`) whose reports carry their actuals and surprises. The default is today, the next session and the rest of its week. - **`CALLS`:** with a ticker, the company's calls, the next one on its own line with its start here and in New York. Alone, the calendar of every company's calls today, the next session and the rest of the week. `--view transcripts` lists the latest transcribed calls instead. - **`DVD`:** `gloom fn DVD KO PEP JNJ` ranks several tickers by yield, with payout, growth, last ex-date and pay date. A bond fund's SEC yield sits beside its distribution yield, and `gloom fn DVD MUB --tax-rate 40.8` adds a muni fund's tax-equivalent yield and muni/Treasury ratio ([research data](research-data.md#bond-funds-sec-yield-tax-equivalent-yield-and-the-munitreasury-ratio)). **The `ERN` calendar** (desktop and web): - The bar's Names filter offers Mine, each portfolio, each watchlist and each sector fund `SECT` charts, and narrows the table and the calendar alike. - Calendar shows a week, a column per day, with companies reporting before the open and after the close as logos, largest first (green or red once reported, by surprise). Range picks the week, from last week to three weeks ahead, and `+N more` shows the rest of a busy day. - Enter or a second click opens a company's reports, and `n` sets an `ALRT` earnings alert on it. #### Which tabs Ticker Research shows Ticker Research shows the tabs that can have data for the instrument. | Instrument | Tabs | |------------|------| | Stocks | The company tabs: analyst coverage, diagnostic, earnings calls, executives, filings, risk factors, hiring, holders, insider and short interest | | Funds | Events, dividends and congress trades. Options and 13F stay for ETFs, closed-end funds and funds of unknown subtype | | Coins, currency pairs, indices | Overview, chart, news and notes | - Options also stays for indices, futures and option contracts. Explicitly classified mutual funds and money-market funds hide Options and 13F. - Tabs sourced from SEC, FINRA and congressional filings are hidden for listings outside the US. #### Extended hours on the headline The Overview headline is the regular session, with one extra line for the extended-hours price. After the close the headline stays at the official close and the After-Hours line under it gives the latest extended-hours price and its move from that close. In pre-market the headline is the last session's close, and only the Pre-Market line changes. `gloom ticker` and the `QQ` cards (`AH` or `PM` where narrow) report it the same way, and `quote`, `compare` and `fn QQ` add an After Hours or Pre-Market column when a row has one. In `--json`, `price`, `change` and `changePercent` are the headline, and `extendedSession` (`PRE` or `POST`), `extendedPrice`, `extendedChange` and `extendedChangePercent` are the extended print, null without one. #### Overnight session From 20:00 to 04:00 New York, Sunday night to Friday morning, a US listing still trades on an alternative venue while its exchange is closed. With real-time data the price is that session's last trade, or the midpoint of its bid and ask while nothing has traded. The headline stays the completed regular session, with an Overnight line under it (`Overnight mid` for a midpoint). The session reads `OVERNIGHT` (`ON` on a narrow `QQ` card or a heat map tile). `quote` and the portfolio and watchlist reports give it an Overnight column (`mid` after a midpoint), and `extendedSession` reads `OVERNIGHT` in `--json`. Delayed data has no overnight session, and the pre-market takes over at 04:00. #### Stale quotes A quote whose last print is older than its venue's latest completed regular session reads `STALE` in the warning color, in `quote`, `compare`, the `ticker` header, the Ticker Research overview and the boards' session column. - **Pre-market with nothing traded yet:** a quote that carries the last session's close reads as that close (`Thu close`), with `Updated` and the report's as-of at that close's time and no Pre-Market figure. The first pre-market trade makes it `PRE-MKT`. A pre-market price of 0 is never shown. - **No prints in an open session:** when the venue's calendar says a session is open and nothing has printed in it yet, a stalled feed and a closure the calendar does not list (TWSE's typhoon days) read alike. `gloom quote` adds `2330.TW (Taiwan Semiconductor Manufacturing Company Limited): no prints today since Thu 22 Oct 05:30 UTC (20h 50m old)` under the table, and the Ticker Research footer reads `No prints today since 2026-10-22 05:30Z`. - Exports keep the state: `session` stays `PRE-MKT`, `sessionLabel` is what the Session column shows (`Thu close`), and `updatedAt` is when the price Last shows was observed. #### What a change is measured from Every change line says what its move is measured from, in muted words after it: the Overview headline, `ticker`'s Change line, `quote` and `compare` (a Chg Basis column), the portfolio header's Day (a watchlist's Avg Day) and the `Day's move` line of `portfolio show --close`. - **Listings:** the close of the venue's previous session, dated by its calendar (`vs Fri 16 Oct close`), with a line under it naming the days the venue was shut (`HKEX closed Mon 19 Oct, holiday`). Venues with no holiday calendar (most of Europe) read `vs prev close`, never a guessed date. - **Futures:** the settlement or last trade their terms name (`vs Thu 15 Oct settle`), otherwise `vs prev close`. - **Coins:** since 00:00 UTC, the previous UTC day's close. A coin whose close cannot be dated to the last two days reads `24h`, and a perpetual always does. - **Totals** over moves from different closes (an HKEX listing beside a US one) read `vs mixed closes`. In exports, `--csv` and `--ndjson` rows add `Chg Basis` and `Chg Basis Note` (`changeBasis`, `changeBasisNote`). In `--json`, `quote` and `compare` add `changeBasis` (`kind`, `date`, the `closed` days, `label`, `note`) to each row, `quote` adds `previousCloseDate`, and `portfolio show --close` adds `dayChangeBasis`. A quote with no comparison shows its price without a change. #### Market boards After the close and through a weekend, the boards' Last and change agree with `gloom ticker`. - `sectors`, `indices` and `movers` (every list), and `fn BI`, `fn WEI` and `fn MOST`, give an extended print an After Hours or Pre-Market column when a row has one, and the four `extended` fields in `--json`. `WEI`, `FUT` and the `GPU` equities board show the regular session and no extended column. - After the close, Gainers and Losers rank by the regular session's move. `gloom movers gainers --session extended` (or `losers`) ranks by the pre-market or after-hours move from that close instead. The line above the table names the ranking (`Ranked by the regular-session move`, `Ranked by the after-hours move`, `Ranked by volume`), as `metadata.rankedBy` does in `--json`. - In the `MOST` pane, click the `AFTER-HRS` or `PRE-MKT` header to sort by the extended move. A narrow `BI` pane gives up the move bar and then the extended column before cutting a sector's name, and a narrow `MOST` gives up MCAP and then 52W%. - The header's SPY is in dollars (`SPY $759.97 -0.52%`), and your base currency follows it under its own label (`base THB`), which a narrow header drops before the market state. - The header's SPY is the regular close once the market is closed. While the pre-market or after-hours session is open it is that session's price and move beside the `PRE-MKT` or `AFTER-HRS` label. The pre-market countdown says `to regular open` and counts to 09:30 New York time (a narrow header hides it when its full label does not fit). **Trending quotes that fail to load.** The `MOST` Trending list and `fn MOST --list trending` name symbols whose quotes could not be loaded. If none load, the pane keeps its previous rows marked stale, and JSON reports set `complete: false` and list `unavailableSymbols` and `errors`. #### THEM Outside the regular session `THEM` shows each member's last regular close and move, as `ticker` does, and its 1W, 1M, 3M and YTD end at that close (YTD measured from the prior year's last close, `YTD vs 31 Dec close`). A pre-market or after-hours print gets its own column and never enters a return. The footer names the close and the snapshot's age (`Fri 9 Oct close · snapshot 12m ago`). `--json`: `metadata.asOf` is that close, with `snapshotAssembledAt`, `snapshotAgeMinutes` and `regularSessionDate`, and each member adds the four `extended` fields. With Pro, `THEM` prices members and themes from real-time quotes: the footer reads `live · snapshot 3m ago` while a session trades, the pane refreshes every 15 seconds, and `fn THEM` reports `live`. Otherwise the board is fifteen minutes delayed. `MOST`'s Gainers, Losers and Most Active, and `movers`, read the real-time lists and say `live`. #### Valuation figures after the close From the close until the next open (overnight, weekend, pre-market), every figure measured at the price uses the regular close, so a P/E times its EPS is the close, never an extended print. That covers `RV`, `valuation`, `fundamentals`, `ticker`, `DES`, the `PF` and watchlist MCAP, P/E and yield columns, `ANR`'s upside, `DVD`'s yield, `PEB`, `RDCF` and `GE`. While the session trades, they follow the live price. - The `RV` pane has a `PRE-MKT`, `AFTER-HRS` or `OVERNIGHT` column after CHG% while a peer has one, and `gloom fn RV` a Pre-Market, After Hours or Overnight column. Its `--json` and `--csv` carry `changePercent` and `marketCap`, in each peer's own currency (`marketCapCurrency`) or the one `--currency` asks for ([research data](research-data.md#relative-valuation-peers-columns-and-currency)). - `valuation` starts with Last, Change and, when there is one, the extended print. Its `--json` adds `price`, `change`, `changePercent`, the four `extended` fields, `marketCap` and `marketCapCurrency`. - `fn RV --csv` has one header in every market state: Last as a plain number in each peer's own currency (named per row in `currency_or_unit`, its ticker in `symbol_or_series`), then each session's print and move (`Pre-Market`, `Pre-Market Chg%`, `After Hours`, `After Hours Chg%`, `Overnight`, `Overnight Chg%`), empty for a peer with none, and `Mkt Cap` followed by `Mkt Cap unit`. #### Portfolio and watchlist reports `portfolio show` and `watchlist show` read the quote as the `PF` pane does: Last and Chg are the regular close and its move after the close, with an After Hours or Pre-Market column when a holding has one. Value and P&L are priced at the latest print unless you ask for the regular close; see [What a portfolio is priced at](#what-a-portfolio-is-priced-at). - A portfolio's `--json` puts Last in `quotePrice` and adds the four `extended` fields (`fn PF` reports `price` and `changePercent` the same way). - `watchlist show --csv` and `--json` print one row per ticker, as raw numbers: `symbol`, `listing`, `name`, `exchange`, `kind`, `currency`, `price`, `change`, `changePercent`, the four `extended` fields, `volume`, `quoteAsOf`, `stale` and `lastTradeDate`. `marketCap` is in your base currency (`marketCapCurrency`), and `fundingRate8h` appears only when the list holds perpetual markets. - A list holding a stale quote adds a Last Trade column (`STALE 2023-03-09`) and a line naming them. Funds and indices have no Mkt Cap (a note names them). A list holding a perpetual market adds a Fund 8H column. #### Earnings-call exports Earnings-call exports and fiscal-quarter lookup inspect at most the latest 200 calls in the requested scope (the interactive list loads 50). When a response fills that limit, exports report `sourceLimitReached: true`, `complete: false` and `truncated: true`: more calls may exist, and a missing quarter is not proof the company had no such call. `totalIsExact: false` marks capped, pending or stale results. #### 13F The ticker research `13F` tab shows fund positions for the ticker: reported value, shares, weight and quarter action. Open a row for its fund detail, and scroll to page more funds. `m` or the Mine filter limits positions to portfolio and watchlist tickers. The `13F` pane's Crowding tab ranks new positions, exits, and weight increases or decreases across the top 25 ranked funds. ```bash gloom fn 13F AAPL --view=ticker-holdings --offset=0 --json # a ticker argument defaults to this view gloom fn 13F AAPL --view=by-ticker # the holders' whole 13F books gloom fn 13F --view=crowding --json gloom fn 13F MU --view=crowding # that ticker's rank in the crowding sample, or says it is not in it ``` The text report opens with the quarters compared, the holder, new and exited counts, and, when the list is longer than `--limit`, which funds are shown and the `--offset` that continues it. `--json` carries `shown`, `total`, `truncated` and `nextOffset`. Headless crowding accepts `--rank=new`, `--rank=exits`, `--rank=increases` or `--rank=decreases`. A ticker reads as one in any case (`fn 13F aapl`, `brk.b` and `BRK-B` list the holders as `AAPL` and `BRK.B` do). A lowercase word that is also in a filer's name, such as `ares`, lists the ticker's holders and adds the command that opens the fund, and a ticker-shaped word with no 13F holders, such as `tiger`, is searched as a fund name. #### HDS `HDS` has three tabs: - **Table** and **Chart** show the 13F institutional holders. On a home line abroad such as `BHP:LSE`, values are in the currency the report names, and a row held as US depositary receipts carries an `ADR` badge. - **13D/G** shows who disclosed more than 5% of the class on Schedule 13D (activists) or 13G (passive holders) in the last four years, one row per filer (`+N` for others on the report). A row shows the latest report's form, the percent of class as filed, the change in points against the previous report, shares, event and filing dates, and the latest 13F move in the ticker (NEW, the share change, EXIT, or a dash). The latest report is the filer's latest disclosure, not its position today. A stake reported under 5% keeps its percentage, marked `<5%` where there is room, and sorts after the 5% holders. Reports of zero are marked `EXIT`. Enter opens the filing in the SEC pane and `o` opens it on EDGAR. ```bash gloom holders CAR --form all # `13d` or `13g` for one kind; `--history` for every report instead of the latest per filer gloom fn HDS CAR --form all --json gloom filings CAR --form 13G # the filings themselves ``` #### 13F fund detail: Overlap and Performance **Overlap.** In a 13F fund detail, open Overlap, search a second fund by name or CIK (or an ETF MEMB covers, by ticker, such as `SPY`), and select it to compare shared positions and weights. Against an ETF it shows the overlap and active share. ```bash gloom fn 13F 0001067983 --compare=0001037389 --json # --compare implies --view=overlap gloom fn 13F 0001067983 --compare SPY # a fund against an ETF's holdings file ``` - `--compare SPY` compares the manager's latest 13F with the ETF's holdings file (the one `fn MEMB SPY` shows). It prints the overlap and the active share, the quarter compared with its filing date and the holdings file's date, and the manager's positions the ETF does not hold, largest first. - A word that reads as a ticker (up to five letters, with an optional class such as `BRK.B`) is an ETF when MEMB covers it, otherwise a manager only by its exact name, so `SPY` is not Spyglass Capital. A CIK or a longer name is a manager lookup, and the report says which was used. - MEMB covers IVV (also read for SPY and SPX), IJH, IJR, IWM and IWB. Any other ticker, such as `VTV`, fails with that list. - `--view=overlap` without `--compare` asks for it. `--compare` with another view fails. **Performance.** `gloom fn 13F 0001067983 --view performance` prints that fund's own row, with the `portfolio import --13f` command that copies its basket. - The return is the ranking's when the ranking gives one, otherwise an estimate from the fund's last two filings (Est P&L of the positions held through the quarter over their value at its start), and the estimate's note says why. - The ranking holds at most 100 funds (a larger `--limit` is read as 100 and says so). **Splits.** A line whose shares and value per share moved inversely by about the same ratio between filings (10x the shares at a tenth of the price) is checked against its corporate actions: - A split between the quarter ends is priced on split-adjusted shares, so a line cut after a 10:1 split reads as a trim, not an add. - A line with no split is a trade and priced as it is, and one whose actions cannot be read is left out (Est P&L shows `--`). - A ticker its company has left (BK became BNY) is looked up under the symbol the company trades as now. **Late filers.** A manager with no 13F for the newest quarter past its deadline (45 days after quarter end) is flagged in a fund search (`fn 13F Pershing`, for the first 10 such funds), in the fund's holdings and filings reports, and under a fund in the 13F pane: - `No 13F for Q2 2026, due 14 Aug` - When EDGAR shows a 13F-NT: `13F-NT for Q2 2026, filed 14 Aug; holdings reported by PERSHING SQUARE INC. | open: fn 13F 0002026053` - When EDGAR could not be asked, the line says only that the loaded filings lack the quarter and that EDGAR was not checked. ### Chart Composer `G`, `GP`, `GIP`, `CMP`, `GF` and `GE` open the same chart composer with different starting presets. #### The data catalog `CAT` opens the data catalog: every series a chart can draw, so you can graph one without typing the expression. - Tabs group the series: securities and options fields, crypto, futures, rates and government bonds, credit spreads and CDS, economic data, inflation, FX, energy inventories, volatility, Fear & Greed, positioning (COT, short interest), valuation, alternative data and your own files. - Each row gives the unit, update frequency, publisher and the expression to type. Search matches every word across those columns, and typing a ticker such as `AAPL` fills in every series that takes one. - `g` charts the selected row, asking for a ticker first when needed. The composer's Series search finds the same entries. - Series from Pro datasets (research attention, hiring, app attention, GPU rental indexes, government awards, perpetuals) need Pro, and the chart says so in place of the line. #### Custom expressions A custom expression can mix unrelated sources on one timeline: ```text G AAPL:price, MSFT:revenue, FRED:CPIAUCSL G GAA/VOO G MSFT:revenue / AAPL:revenue ``` Series are separated by commas, and tickers separated by spaces are a list too: `fn G AAPL MSFT` charts both, as `fn G AAPL,MSFT` does. Words that are one thing, not tickers side by side, are refused with what to write: a Bloomberg code (`AAPL US Equity` reads as `AAPL`), a currency pair (`EUR USD` is `EUR/USD`) and a series whose field has spaces (`MSFT:net income`, one series among commas). `A/B` charts the ratio of two series and `A - B` the spread. A slash that is part of the symbol stays one series (`EUR/USD`, `BTC/USD`). A formula adds and subtracts series, each times a number, and charts the result in the Formula panel. The number goes on either side of its series (`HO=F*42`), and only the whole formula, in brackets, is divided by a number: ```text G "42*HO=F - CL=F" G "(2*42*RB=F + 42*HO=F - 3*CL=F)/3" ``` A futures price is in its contract's unit (heating oil and gasoline USD / gallon, crude USD / barrel), so the 42 turns a per-gallon series into per barrel and both formulas above are crack spreads in USD / barrel. Series in different units do not add up. `catalog crack` lists the heating-oil and 3:2:1 cracks, and so does G's series search (`n`, then `crack`): picking one adds its legs and replaces the chart's formula. #### Leveraged and inverse funds `CMP` with a leveraged or inverse fund (TQQQ, SQQQ, SOXL, UVXY) draws the fund's daily objective beside it: its factor (from the sponsor's page, as `fn ETF` shows it) times the index fund's return each session, compounded (`3× daily QQQ` beside TQQQ). The index fund joins the comparison when it is not in it. The Decay panel measures, in percentage points over the period in view: - `TQQQ decay vs 3× daily QQQ`: the fund's return minus the daily line's (fees, financing cost and tracking). - `3× daily QQQ decay vs 3× QQQ`: the daily line's return minus three times QQQ's. This is compounding: a fund that resets daily loses it in a market that swings and gains it in one that trends. ```text fn CMP TQQQ,QQQ --rangePreset 1M ``` Returns are from closing prices, so they leave out distributions. The line needs daily bars: weekly or monthly bars (`--chartResolution 1wk`) or a single session leave it out, with a warning. A fund that resets monthly, or whose benchmark no fund tracks one for one, gets no line. #### Your own series Put a CSV file in the `series` folder of your data folder (`~/.gloomberb/series`, or the directory `gloom version` names). It appears in the catalog's **Your series** tab the next time the catalog opens, chartable against anything else, and each chart rereads the file. The web app has no file access. - The first column is the date (`2024-03-01`, `2024-03`, `2024` or an ISO date and time). Each further column is a series, and an optional header row names them. Commas, semicolons and tabs all work as separators, and an empty or `.` cell is a missing value. - Lines starting with `#` above the data set what the catalog shows. Without them the file name names the series, the unit is a plain number and the frequency is read off the dates. ```text # name: Shipping index # unit: index # frequency: weekly date,value 2024-01-05,1234.5 2024-01-12,1251 ``` `unit` takes the values plugin series use (`%`, `bp`, `index`, `USD`, `billion USD`, `thousand barrels/day`). #### Series and panels Open **Series** to add, remove, reorder or hide series and choose each one's field, chart style, transform, axis, panel, period and panel scale. Price data supports candles, OHLC, HLC, line and area. Scalar data supports line, area, step, column and point. Panels can use independent left/right axes and linear or logarithmic scales. #### Financial periods - `GF` opens on quarterly bars. Set a series' Period to Annual (or `fn GF --period annual`) for fiscal years. A company that reports no quarterly figures, such as a semi-annual filer, says so instead of switching to annual. - `GE` opens on fiscal years. Set Period to Quarterly (or `--period quarterly`) for the multiple on the trailing twelve months at each quarter end. - Most US filers report no fourth-quarter EPS and charts do not reconstruct it ([research data](research-data.md#financial-statements-and-valuation)), so quarterly history usually covers only the latest few quarters. - A saved pane keeps its period, and the legend names the fiscal period as FA's columns do (`Q3 FY26`, `FY2025`, `TTM Q3 FY26`). #### Toolbar, indicators and alignment The toolbar controls date ranges (preset or exact), intervals from one minute through monthly, the chart mode, technical indicators and pair formulas. - Indicators: volume, SMA, EMA, Bollinger Bands, VWAP, anchored VWAP, volume profile, RSI, MACD, ATR and Realized Volatility (window and estimator in pane settings). Formulas: ratio, spread and rolling correlation. - Mixed-frequency values use as-of alignment: fundamentals use filing dates when available, and sparse series carry forward only after becoming available. - Missing publication dates show behind the warning indicator in the chart footer (click it or press `!`). #### Bar sizes **Bars** (`b`) lists 10m, 2h, 4h, 2D and 3D beside the sizes a source serves, and builds them from shorter bars. **Custom…** takes any count of minutes, hours, days, weeks or months (`90m`, `6h`, `5D`, `2W`, `3mo`). A capital `M` alone is refused, since it could mean minutes or months. - Each bar takes the first open, highest high, lowest low, last close and summed volume of the bars it holds, so the last bar of a session can be shorter. - Minute and hour bars start at the listing's session open (09:30 New York for a US stock, 17:00 Chicago for CME futures) and never span two sessions. Day bars count trading days from 1 January, week bars from the year's first Monday, month bars from January. - A built size is saved with the pane and its share link. `fn G` and `shot G` take the same sizes as `--chartResolution`. #### Spreads, ratios and correlation **Spread** is the first input minus the second times its configured multiplier. It needs matching dimensions, currencies and scales, and market prices also need a declared per-unit basis (a future's is its contract's unit). An incompatible formula is unavailable and shows in the chart or report errors. No FX conversion happens, and display transforms (percent, index) are not applied before subtraction. **Ratio** keeps derived units such as USD/EUR or 1/share and has no value at a zero denominator. When either input has unknown units, the number is still available with unit `unknown`. **Correlation** uses matching observation times when inputs have different frequencies. #### Crosshair Moving the crosshair along time, with the pointer or the arrow keys, reads every series at that date. The legend shows every series' value there in its own unit and returns to the latest values when the pointer leaves. A series with no observation at that time shows its last value before it, dimmed with its date. The time charts in a layout tab share one crosshair, including the research pane's Chart tab and the time charts in other panes (IV history, a macro series, Fear & Greed, the chart above a table). While it is on one chart, the others draw their vertical line at the same time. Esc on any chart clears it everywhere. Charts with an x axis of their own (curves, smiles, scatter plots), the overview's price chart, and charts in another layout tab or a popped-out window do not follow it. **Pinning.** `p` on a focused chart, or `pin` in its footer, pins the crosshair where it is, and every chart in the tab holds that moment (the footer then offers `unpin`). - While pinned, the arrow keys on any chart move the pin a bar at a time. Esc or `p` lifts it. Where `p` does something else (the correlation window in a relationship chart), use the pane menu (`.`). - The pin belongs to the tab and goes when the last chart you can move it on closes, or the tab does. - News feeds in the tab (`N`, `CN`, industry news) select the newest story published by the pinned moment and show later ones muted. Time and sales (`TAS`, `QR`) selects the print or quote at or just before it. #### Pan and zoom Dragging the plot, the scroll wheel or trackpad, and `a`/`d` or Shift with the arrow keys pan the chart, loading older bars as it moves. Where a listing's bars at the chosen interval run out, the pan stops at the first one and the footer says where they start. Choosing the range already selected, by its number key or a click, returns a panned or zoomed chart to that range, as `0` does. Ctrl with the scroll wheel and a trackpad pinch on desktop and web zoom time around the pointer. `+`/`-` zoom from the newest bar in view. Dragging the time axis zooms the same way (left in, right out, double-click to fit). - Each panel's value axis scales on its own: drag it up to stretch the values, down to squeeze them, or scroll over it to zoom. A panel scaled by hand stops fitting its values to the bars in view, and an `Auto` button at the foot of its axis, a double-click on the axis, or `0` fits them again. - `0` and Reset Zoom in the pane menu fit every axis. #### Panels, tools and legend - **Resize:** on desktop and web, drag the line between two panels (a double-click restores the split). On a focused chart, `Shift+Up` and `Shift+Down` make the top panel a row taller or shorter (the terminal too), and the pane menu has Reset Panel Heights. - **One panel full size:** a double-click on a panel's plot gives it the whole chart (two quick presses in the terminal). A double-click again, or the `All panels` button, shows the rest. - **Drawing tools:** `Shift+T`, Hide Drawing Tools in the pane menu, or the chevron at the end of the tool bar folds the bar to one button. - **Legend:** `Shift+L`, Collapse Legend in the pane menu, or the chevron in the legend's left margin folds it to the first series and a count (`+5`). A folded series still draws. These are kept with the pane. #### Intraday sessions On intraday charts, bars outside the venue's regular session (pre-market, after-hours, after an early close) sit on a tinted band, and the terminal marks the regular session's start and end with a dotted rule. A venue without known hours has no band, and US intraday history covers the regular session, so the band appears where a source sends extended-hours bars. #### Trader studies In the Indicators dialog (`i`), the highlighted study's setting sits beside Done: Period (`p`) for SMA, EMA, Bollinger, RSI and ATR, Bands (`b`) for VWAP, Rows (`n`) for the volume profile and Anchors (`a`) for anchored VWAP. - **VWAP** is the volume-weighted average of the typical price, (high + low + close) / 3, from each session open. It needs intraday bars, and Bands add and subtract a whole number of volume-weighted standard deviations. - It restarts at the venue's open: 09:30 New York for US listings, 17:00 Central the evening before for CME Group and Cboe VIX futures, and each ICE U.S. contract's published open (Coffee 04:15, Sugar 03:30, Cocoa 04:45, Orange Juice 08:00 New York, Cotton 21:00 and the dollar index 20:00 the evening before). - A venue without known hours restarts at local midnight, or at midnight UTC for crypto. - **Anchored VWAP** runs the same average from bars you pick and never restarts. Turning it on, or `v` while it is on, waits for a click on a bar (or Enter at the keyboard cursor; Esc cancels). Anchors also take a date (`2026-09-30`) or an exchange time (`2026-09-30 10:00`), up to eight per chart. - **Volume profile** spreads each bar's volume over its high-low range into equal price rows across the bars in view, so it follows pan and zoom. The busiest row is the point of control (a dotted level), and the value area grows from it until it holds 70% of the volume. - **ATR** is Wilder's average true range in its own panel. The volume profile and price levels need the price in its own values, not a percent or index display. #### Price levels The level tool (`Shift+H`, or `═` in the chart toolbar) draws horizontal price levels that belong to the ticker, not the pane. Every chart of that listing shows them and they sync with your account. - With the tool in hand, a click adds a level, dragging moves it, and Enter adds one at the keyboard cursor's price. `[` and `]` pick one, Up and Down move it, Backspace or Delete deletes it. With no tool in hand a click on one of yours picks it. - `Shift+A` on a level sets an ALRT price alert there: above when the level is over the current quote, below when it is under, crosses when it is on it. Levels with an alert, and active alerts on the ticker set elsewhere, draw in red. Change an alert's own line in ALRT. - With the order ticket beside the chart, its order and draft lines also move with a plain drag, and the level keys move them too. A working order's move opens its change in the ticket for review ([trading](trading.md#trade-from-the-chart)). #### Session low and high `gloom fn GIP ` ends with the session's low and high and the UTC time each traded (`USDT-USD:CCC session low 0.99833 at 2026-10-17 11:30 UTC`; over several sessions they read low and high). `GIP` dates sessions on the listing's exchange clock, read from its exchange or its suffix (`RMS.AX` is the ASX). A bare symbol with no known exchange is dated in UTC. A US listing's bars are the regular session only, from the 09:30 New York open, and the report says so (in `--csv`, as a `# note:` line): an 08:30 release falls before its first bar. `--csv` writes each price as the decimal it traded at (`85.1`, not the feed's `85.099998`; a sub-penny print such as `86.3775` stays), under `Open,High,Low,Close,Volume` with no `Value` column repeating Close; `--json` keeps `value` beside `close`. A zero or negative price is kept for a futures instrument. For any other instrument a nonpositive close in the window makes the result unavailable, and JSON metadata keeps the rejected values and dates in `intradayPriceDomainFailures`. ### Markets, News, and Macro | Shortcut | Function | |----------|----------| | `TOP` | The 20 top-ranked market stories | | `HM` | Market heatmap of the 500 largest US stocks by sector and industry, large US ETFs, and the portfolio pane's selected list | | `MOST` | Top gainers, losers, most active, and trending tickers | | `HILO` | Session new highs and new lows with 30s/1m/5m momentum | | `FLOW` | Unusual options activity: sweeps, blocks and large premium. Vol/OI divides the contract's day volume by its latest open interest | | `PM ` | Polymarket and Kalshi prediction data ([Prediction Markets plugin](https://github.com/gloom-sh/gloom-prediction-markets)) | | `N` | News feed | | `CN ` | Ticker news | | `NI [code]` | News by topic: `MNA`, `CB` (central banks), `ENERGY`, `METALS` (metal prices, futures and bullion, not miners' releases), `REG`, `CRYPTO`, `EARN`, `IPO`, or a sector: `TECH`, `FIN`, `HEALTH`, `INDU`, `CONSD`, `CONSS`, `COMMS`, `MATS`, `UTIL`. `LTR` lists public fund and investor letters as links | | `SUB` | Authenticated Substack reader feed ([Substack plugin](https://github.com/gloom-sh/gloom-substack)) | | `FIRST` | Breaking news | | `TWIT ` | Ticker-related market posts | | `TBO` | TheBuildout infrastructure intelligence | | `CG` | Congress trading disclosures | | `WEI` | Global equity indices | | `MAP` | World map with trading venues, country names and layers (`MAP venues` for venues alone) | | `TAS ` | Time and sales: trade prints, observed-window VWAP and large prints | | `QR ` | Quote recap: NBBO history with sizes, venues and spread (the same pane on its NBBO tab) | | `EM ` / `EEO ` | EPS estimate revisions, analyst breadth and surprises. `--period YYYY-MM-DD --frequency quarterly` pins a fiscal period | | `KPIS ` | Company operating KPI tables, charts, revisions and verbatim evidence (Pro, Free preview) | | `GUIDE ` | Structured management ranges, raise/cut tracking and later actual versus guide (Pro, Free preview) | | `GUID ` | Company EPS guidance cited from filings and transcripts, against consensus (the Guidance tab of `GUIDE`) | | `FUT` | Futures quote aliases across index, equity sectors, rates, energy, metals, grains and softs, livestock, and FX | | `RRG` / `GRR` | Weekly relative rotation of sectors or a watchlist against a benchmark, with dated trails | | `BT ` / `BTST ` | Backtest a long-only indicator rule on daily history against buy-and-hold | | `EQS` | Equity screener over the stored Cloud universe: valuation, growth, margins, short interest, insider and 13F criteria, saved screens and export | | `PERP [market]` | Perpetual funding, open interest and premiums: a board, rankings and one asset across venues (Pro history; free preview) | | `CRYP` | Top crypto assets by market cap with live prices, 7D, 30D and 1Y returns, 24h volume and market cap. Stablecoins have their own tab | | `ETFF` | Daily net flows of the US spot bitcoin and ether ETFs, fund by fund in US$ millions, with the last 5 and 20 days and the running total since launch | | `ECO` | Economic events and releases, grouped by day and timed in UTC. Opens on high-impact releases until you pick another impact | | `ECST [statistic]` | Economic statistics: inflation, labour, growth, consumer, housing, rates | | `GC [curve] [date]` | Government yield curves (UST, TIPS real, breakeven, euro AAA, Bund, Gilt, JGB, Canada) with spreads and percentiles, a compare date, the one-year-forward curve, a World tab and USD SOFR Swaps. CLI: `--curve`, `--date`, `--compare 1D` (or 1W, 1M, 3M, 1Y, or a date), `--tab world`, or `--tab swaps --tenor 10Y` | | `WIRP` / `FFIP` | Fed funds futures implied FOMC path, conditional target probabilities, SOFR contracts and Fed projections | | `BTMM` | Money markets: funding rates, Treasury bill curves and Federal Reserve liquidity | | `YAS` | Fixed-coupon bond calculator: price/yield, accrued interest, duration, convexity, DV01 and Treasury spread | | `TRACE [issuer, symbol or CUSIP]` | FINRA corporate and agency bond last sales. Alone, the latest prints market-wide | | `CBR` / `ECFC` / `CBRT` | Policy rates of the G20, SNB, Norges Bank, Riksbank and RBNZ, last observed moves and one-year history | | `CTM [root]` | Futures contract curve, historical ghosts, roll yield and open interest, including `CTM VX` and CME crypto (`CTM BTC` adds each contract's premium to spot and annualised basis, `(Last / spot - 1) × 365 / days to expiry`) | | `COT [code or name]` / `CFTC [code or name]` | CFTC positioning extremes, weekly changes and historical percentiles, by root or commodity name (`COT KC`, `COT coffee`), including CME crypto (`COT BTC`) | | `AUCT [search]` | Treasury auction results: auction rate (a TIPS rate is a real yield and an FRN's a spread in bp), stop-out versus average, bid-to-cover, indirect, direct and dealer takedown, and size | | `VIX` | VIX 9D through 1Y cash-tenor curve, VIX and VIX 3M history and the 3M/30D ratio | | `VOLS` | Cross-asset volatility indices, daily changes and one-year percentiles | | `CRD` | Credit spreads | | `VAL [indicator]` | Whole-market valuation: Buffett, CAPE, excess CAPE yield, Tobin Q, investor equity allocation, dividend yield, margin debt, cap/profits, cap/M2 | | `CDS [ticker]` | Single-name corporate CDS: the issuers traded in the last 5 days, or one issuer's 5Y spread, history and trades | | `IPO` | Upcoming and recent IPOs worldwide | | `HALT` | US trading halts with reason and resumption times | | `DIST` | Distress records: 8-K bankruptcy, obligation and listing filings, going-concern disclosures, Taiwan listing designations, French and UK insolvency notices ([details](distress-monitor.md)) | | `TV` | Live business news television ([TV plugin](https://github.com/gloom-sh/gloom-tv)) | | `BI` | S&P 500 sector performance | | `THEM [theme]` | Thematic baskets with equal-weight returns and breadth, and each theme's members (the Themes tab of `BI`) | | `MEMB ` | ETF holdings with weights, member returns, daily contributions and index changes | | `FXC` | FX cross rates: the majors, or up to 45 currencies (`gloom fn FXC --currencies USD,ZAR,NGN`; `gloom catalog FXC` lists the codes) | | `FNG` | Fear and greed market gauge | #### Market function notes - **`ECST`:** `fn ECST` prints the 2s10s spread in bp and takes `--range 5Y|20Y|ALL` for the window of its percentiles, highs and lows. The daily rates add their 1D and 1W moves ranked against the series' whole history (`1D move -1bp · 21 pctl since 1962`), and Treasury yields name their 15:30 ET cut-off ([move ranks and cut-offs](research-data.md#was-it-a-big-day-move-ranks)). - **`TRACE`:** an issuer name (`TRACE whirlpool`), a TRACE symbol root (`TRACE WHR`, exactly: not `WHRL`) or a 9-character CUSIP asks FINRA for that issuer's bonds, newest sale first (the first 100, and it says so). Matured bonds are left out and perpetuals kept. - A stock ticker with no bonds under its own symbol is asked again by the company name its quote gives (`TRACE CMLSQ` shows CUMULUS MEDIA and says so). - Nothing found says `No prints for on .` - **`AUCT`** searches by type, benchmark (`AUCT 10Y` finds the 10-year note and its reopenings), term, CUSIP or date. Windows reach back 10 years (`--historyDays 3650`) or to the first auction on 1979-10-31 (`--historyDays all`). - **`CDS`:** with no argument, the issuers traded in the last 5 days, most active first, with each one's 5Y spread and its 1W and 1M moves (`fn CDS --sort 1m`, in points upfront past 2,000bp: `57.6 pts`). With a ticker or issuer, its 5Y spread, history and trades. `fn CDS F --csv` carries the same figures, `--csv --section daily` the daily 5Y levels. - **`TBO`** keeps loaded data when a session, subscription or token check fails and says access is unknown. Retry the initial error with Retry, or press `r` to refresh a loaded table. #### Heat map (HM) `HM` sizes each stock by how far it moved today, up or down alike, so the movers are the big tiles whatever their company's size. Tiles are colored by the day's move, from a muted tone near flat to the full down or up color at 3%. A name with no move yet is a quieter grey. **Size by** (settings, every tab but a portfolio's): - **Day move** (default on **US Stocks** and **US ETFs**): a +5% and a -5% name get the same area. Names that moved less than 0.25% or have no move yet take the smallest tile. - **Market cap**: the largest names dominate. **Square root of market cap** gives mid-size names room (the `√` button beside the title switches it with Day move). ETFs use net assets. **Layout.** **US Stocks** groups the 500 largest US stocks into sector blocks (biggest top left) and industries. Names too small to draw, and the few without a sector, sit in **Other** at the bottom right. Hovering a tile shows its name, move, price, market cap and volume. **US ETFs** is the same map without sectors. **Names** draws the largest 100, 150 or 500 names (default) on US Stocks, and up to 160 on US ETFs. **Live streaming.** With it on, colors follow the quote stream, largest names first, real-time with Pro and delayed otherwise (the footer says `live`, `mixed` or `polling`). - In the pre-market and after hours a streaming name shows that session's move from the regular close, marked `PM` or `AH`. - Names outside the stream follow a snapshot refreshed every 15 seconds with Pro while the regular session trades, otherwise fifteen minutes behind and refreshed each minute. **Colour by** in the `HM` settings picks the session the tiles show. **Active session**, the default, follows the pre-market and after hours as above. **Regular session** never shows extended trading: once the session is over a tile keeps that session's close and move until the next one opens. **The footer** says what the board is: `top 500 · Oct 9 session · as of 16:00 ET · checked 2m ago` (names covered, the completed session shown outside the regular session, its close in New York time, and when the app last got it). While the regular session trades it gives when the board's prices printed instead. A refresh that fails says `refresh failed` and keeps the rest. #### HM in the CLI and the portfolio tab `gloom fn HM` reports the map by sector from the same snapshot the pane starts from: each sector's names, total market cap and share of the board, its market-cap-weighted day move, how many names rose and fell, and its best and worst name. - `--group industry` breaks it down by industry, and `--universe us-etf` summarizes the ETF board as one group. - `--json` adds the board's figures in `data.metadata.board`. A name with no move yet counts toward size but not move or breadth (`data.metadata.noMove`). `HM` has a third tab, named for the list open in the portfolio pane (your first portfolio when none is open). - It sizes a portfolio's holdings by market value in the portfolio's currency, whatever **Size by** says, and a watchlist's names by the square root of their market cap in your base currency. - A name without a position, quote, market cap or exchange rate gets the smallest tile and no figure, and past 160 names the smallest tiles are left out (the footer says so). - **Link to portfolio** in its settings switches the heatmap to that tab whenever the portfolio pane changes list. `3` opens the tab, and `[` / `]` step through all three. An open theme in `THEM` and the Members tab of `MEMB` add two entries to the pane menu (`.`): **Open Members In…** opens the members in `RRG` (up to 24), `CORR` (2 to 10), `SIW` (up to 60) or `RIPL` (up to 10), and **Save as Watchlist…** saves the first 100 members to a new watchlist. A `MEMB` search narrows both to the holdings it matches. #### News, Congress and bond tools News rows credit the article's publisher and open its original URL. The managed news feed includes only articles whose publisher and original link can be verified, and custom RSS and Atom feeds use each item's source when supplied. If a feed fails, News keeps any available stories and shows the failure in its footer. A story opened from `SRCH` or a news pane is set for reading: headline, source and time, the tickers it names as chips (click one, or `t`), then the text. A long `SRCH` story shows a **Key facts** list and about a screen of text, with the rest behind **Read more**. Space and Shift+Space page, `]` and `[` jump between sections, `n` and `p` open the next and previous result, and **Show Original Text** in the pane menu (`.`) shows the text as indexed. **Congress.** Ticker Research has a **Congress** tab for House and Senate transactions in the ticker, and the **Chamber** filter narrows `CG` and the tab to one chamber. - Scroll to append filing windows. `n` or its footer action continues a window with no matching transactions, and after the year's filings `p` appends the previous year. - Select a trade for its disclosure details. `m`, `t` and `o` open the member, ticker and source filing. - The CG **Tickers** tab groups the loaded trades by symbol (Enter opens that ticker's disclosures). `f` opens the filters (side, owner, asset category, minimum dollar amount). `i` or **Mine** limits the view to portfolio and watchlist symbols. A `!` beside lag marks disclosures filed more than 45 days after the transaction. - Congress Trades includes returns since the transaction and filing close. Members includes party, median stock return and buy hit rate, and opens to current committee assignments. Missing prices stay blank. ```bash gloom fn CG AAPL --year 2026 --json # use --filingOffset and --offset with the returned pagination metadata for more gloom fn CG --tab tickers --side BUY --minAmount 50001 --json gloom fn CG AAPL --owner spouse --assetType option --json ``` **`YAS`** opens a bond form: settlement, maturity, annual coupon and either yield percent or clean price per 100 face. `e` starts editing at Settlement, Tab and Shift+Tab move through the fields, Escape stops editing, and `m`, `f`, `d` and `n` switch the mode, frequency, day count and end-of-month schedule. The Cash flows and Sensitivity tabs keep the same terms. ```bash gloom fn YAS --settlement 2026-09-22 --maturity 2031-09-15 --coupon 5 --yield 4.25 --json ``` That returns valuation, cash flows and yield shocks. Use `--price 103.333937` instead of `--yield` to solve yield, and add `--frequency 1|2|4`, `--day-count act-act-icma|30-360-us` and `--end-of-month` as needed. `gloom shot YAS --tab valuation|cashflows|sensitivity` takes the same inputs. Local calculations work without Treasury data. #### Futures board (FUT) `FUT` keeps each rolling quote alias as its symbol and names the contract it quotes, the root's front month. Gloom Cloud rolls an alias (CL=F), like the first generic (CL1), on a stated roll date, which `quote CL=F` prints under Rolls. - From then until the old month stops trading the row names it: "WTI Crude Oil Dec 2026, rolled (Nov expires 20 Oct)". The most active month is named when it is another month: "WTI Crude Oil Nov 2026, Dec most active". - `quote` on a deferred contract or a later generic (NGF27.NYM, NG2) prints the front contract and its price, and the quote, chart and `history` follow the same month. - Generic tickers take OI for the open interest switch (CL1OI). UNIT says what a price counts, as `quote` does ("USD / barrel", "US cents / bushel"). - Search matches the root's name and code. `FUT TTF` (`gloom fn FUT TTF`, `shot FUT TTF`) opens the board searched for that contract. - `--tab markets|inventories|positioning|crops` opens the workspace on that board (`gloom fn FUT --tab inventories`). FUT takes no other option and refuses one it does not know. - FUT and CTM list COMEX metals (HG copper, ALI aluminium), not LME or Shanghai (SHFE) contracts. The IMF's monthly world prices are the nearest public series: `gloom fred PCOPPUSDM` and `gloom fred PALUMUSDM`, in USD per metric ton. FUT's 1W, 1M and YTD columns are returns on the contract the row names (LEZ26 for "Live Cattle Dec 2026"), not on the alias, whose continuous series jumps at every roll. - A contract listed after the baseline date shows no return for it (Treasury futures list three quarters ahead, so their YTD is blank in the second half of the year). - Dutch TTF gas names no month, so its front contract is the one, among the next three months, whose last close is nearest the quoted price. **`BTMM`** opens Rates, Bills and Liquidity views. Select a row (Enter or click) for its dated history, one-year range and source. `h` and `l` switch views, `o` opens the selected FRED series, `r` refreshes. Reports take `gloom fn BTMM --tab rates|bills|liquidity` and `--json`. **`CBR`, `ECFC` and `CBRT`** open the Central Bank Rates board: each row's policy rate or target range, last observed move and date, one-year percentile and history. - Select a row (Enter or click) for the source instrument, reporting lag, one-year range and each bank's next decision from its published calendar. `o` opens the official source, `r` refreshes. - `gloom fn CBR --json` carries each row's central bank, source series, link, next meeting and a citation line (`--history` adds the one-year history). **`IPO`** lists deals on the main US, Asia-Pacific and European exchanges from the last three months and the next six (the All, US, APAC and Europe tabs pick the region). The list runs in this order: deals in their offer now (`offering`), upcoming deals, `overdue` ones (listing day passed with no pricing or first session reported), priced and listed deals, then postponed deals. - `/` searches company names in either script, tickers, markets, countries, status and the region's name. The word `pending` lists deals not priced yet. `IPO japan` opens the pane on that search, as `gloom fn IPO japan` reads it. - DATE is the listing date in the venue's calendar, dimmed while expected. PRICE is the offer price once set, else the range, in the deal's currency (London in pence). SIZE is the money raised in US dollars. RETURN is the first session's close against the offer price. Enter or click opens a deal's ticker once it has one. - `gloom fn IPO --region apac --status upcoming --json` returns the same deals. `--status filed` or `--status withdrawn` returns the filings and withdrawn deals the pane leaves out. `PERP` opens the [perpetuals board](perpetuals.md), and `PERP [market]` that market's History. **`CRYP`** opens the top 100 coins by market cap, with stablecoins on the second tab. Prices refresh every 15 seconds and stream in real time where the plan allows. Enter or click opens the coin in the ticker pane, column headers sort and `r` refreshes. `gloom fn CRYP --json` returns the board, and `--list stablecoin` the stablecoins with their supply ([stablecoin supply](research-data.md#stablecoin-supply)). ### Workspace and App Controls | Shortcut | Function | |----------|----------| | `PF [portfolio or watchlist]` | Portfolio and watchlist workspace. With a name or id, in any case, it opens that portfolio or watchlist | | `PORT` | Portfolio risk and sector exposure | | `ALRT` | Price, filing, news, earnings and market event alerts, with delivery history | | `SA ` | Create a price alert | | `AI ` | AI screener ([BYOK AI plugin](https://github.com/gloom-sh/gloom-byok-ai)) | | `AGENT` | Local AI research workspace ([BYOK AI plugin](https://github.com/gloom-sh/gloom-byok-ai)) | | `CHAT [channel]` | Gloom Cloud chat | | `DM @user [@user...]` | Open or start a direct or group chat | | `ACM` | Gloom Cloud account settings | | `NOTE` | Notes | | `THESIS [tickers]` | Investment theses board (Gloom Cloud) | | `IBKR` | IBKR trading pane | | `BR` | Broker connections | | `CHG` | Changelog | | `HELP` | Open shortcut and layout help | | `AW` / `AP ` | Add a ticker to the active watchlist or portfolio. `AW` also takes a pasted list of tickers | | `RW` / `RP ` | Remove a ticker from the active watchlist or portfolio | | `PS` | Open focused pane settings | | `LAY` | Open the layout browser to switch, publish, or add layouts | | `DESK [desk]` | Add a ready-made desk as a new layout tab: equities, options, futures and commodities, rates and credit, FX and macro, or active trading | | `LMA ` | Layout and pane arrangement actions | | `WIN move\|resize` | Move or resize the focused window | | `GL` | Tidy all windows | | `SB` | Toggle the status bar | | `VF` | Toggle quote value flashing | | `TH ` | Change color theme. The list shows each theme's id, the one `gloom config set theme ` takes. `gloom config themes` lists them, `colorblind`, `colorblind-light` and `high-contrast` included | | `FONT+` / `FONT-` | Increase or decrease desktop font size | | `CONN` | Connection health | | `POLL` | Political polls from VoteHub ([Polls plugin](https://github.com/gloom-sh/gloom-polls)) | | `UPGRADE` | Account upgrade | | `MCP` | Connect Claude Code, Codex, Cursor or another MCP client to Gloom | | `CR` | Cycle chart renderer | | `LANG ` | Change interface language (`auto`, `en`, `es`, `zh-CN`, `zh-TW`, `ja`, or `ko`) | | `PL ` | Manage plugins | **Toggle Presentation Mode** in the command bar hides the header and the status bar until you toggle it again. The pane fullscreen key (`Ctrl+Shift+F`, `Cmd+Shift+F` on a Mac) then fills the window with one pane. The desktop app keeps the header, as it is the title bar. It is saved as `"presentationMode": true` in the config. In `PF`, `a` adds a ticker to the open manual portfolio or watchlist and `d` removes the selected one after a confirm. - Removing it from a portfolio deletes its position there. Its notes, alerts and other lists stay. - Broker portfolios and team lists have no `d` (the next sync would put a broker ticker back, and everyone shares a team list). `RW` and `RP` still edit a team list. - In the add row, a symbol with a colon (`NET:`) opens that symbol's exchanges, and the one you pick joins the list. When the `PF` table comes back into sight after two minutes away, LAST is tinted for six seconds on each row whose price moved since you left (green above what LAST showed then, red below). A key or a click clears the tint. **Moves Since Last Seen** in the pane's settings sets the time away (30 seconds, 2 minutes, 10 minutes) or turns it off. `gloom fn PF --json` returns a portfolio's positions, broker or manual, valued as `portfolio show` values them. - Each row has shares, average cost, last price, market value and unrealized P&L in the portfolio's currency, its weight of the total with cash (see [Cash, target weights and rebalancing](#cash-target-weights-and-rebalancing)), and when its price is from. Rows run largest first, then the cash line. With target weights set, each row adds its target, drift and the trade that reaches it. - `--close` values them at the regular close (see [What a portfolio is priced at](#what-a-portfolio-is-priced-at)). - `--limit` caps the rows (50 by default, at most 200). The totals always cover every position. - Name the portfolio or watchlist by its ID or name. Without one it reads your first portfolio. A watchlist returns its tickers with their quotes. Published layouts keep portable pane setup and state (searches, chart viewport, drawings). Credentials, accounts, portfolios and pane fields marked private stay local. Publishing copies a durable `term.gloom.sh/l/...` link. The AI screener, the AI research workspace and the Ask AI research tab come from the [BYOK AI plugin](https://github.com/gloom-sh/gloom-byok-ai), which connects your own provider account. The selected model writes the screener's reasons, so review the cited fiscal periods, metric values and sources in company research. Missing data is not evidence that a company meets a criterion. ### Filing event alerts Open `ALRT` and choose **Events** to follow Congress trades for your portfolio and watchlist, a representative's or senator's first and last name (optionally `name:district` or `name:state`), or a fund's numeric SEC CIK. Use **Add Event Alert** in the command bar, or the pane's add action. Enter or the pause action toggles a rule, delete removes it. Rules sync with your price alerts. Push needs Cloud sync and a registered mobile device, and the phone's notification settings have separate Congress and 13F switches. **Add Event Alert** also creates market and research rules for a US-listed symbol: - confirmed earnings date (days before), SEC filing type (8-K, 10-K, 10-Q, S-1, SC 13D/G, 6-K, 20-F), news keyword (symbol optional), analyst upgrade or downgrade, new 52-week high or low - unusual volume (multiple of the prior 20-session average), short interest change (percent between FINRA settlements), open-market insider buy or sell - an option IV spike for one OCC contract (Pro), and an IV level on a symbol - options flow (Pro): a print at or above a premium (default $1M, typed as `1,000,000`, `$250k` or `1.5m`) on one symbol, or on any name in your portfolio and watchlists when the symbol is blank, optionally calls or puts only and sweeps or blocks only The **Events** tab shows each rule's last checked value with its one-year percentile and date when the pane is wide enough, and a flow rule its latest matching print. **History** lists the alerts that went off, newest first, with the rule, the figure and the quote behind it (`r` refreshes). The phone's notification settings have one switch for these market and research alerts. An **IV level** alert follows a symbol's 30-day at-the-money IV (in %) or 30-day 25-delta risk reversal (25D call IV minus 25D put IV, in vol points), above or below a level. Its figure is the **1M** row of `OVDV`'s Table. - The running app checks it every 15 minutes, signed in or not, and notifies once when the level is passed. The rule then reads **Alerted** until you re-arm it (`m`, or `gloom alerts rearm `). A rule added or re-armed while the reading is already past its level goes off at its first check. - Readings stay on the device and only a rule going off or changing is synced. Gloom Cloud does not check these, so they reach no phone. From the shell, `gloom alerts add` takes the same rules: ```bash gloom alerts add IBIT iv above 50% # 30-day ATM IV above 50%; the unit is optional gloom alerts add SPY rr below -5.5 pts # 30-day 25D risk reversal below -5.5 vol pts gloom alerts add AAPL271217C00300000 iv spike 5 gloom alerts add AAPL news buyback # alerts add news "rate cut": any company gloom alerts add NVDA flow 5m calls sweeps # flow alone: your portfolios and watchlists, $1M and up ``` A symbol is read as `gloom quote` reads it and must be a US listing, as in the dialog. `v` (view, also in the footer and the pane menu) opens what the selected row follows, on **Prices**, **Events** and **History**: | Rule | Opens | |------|-------| | a security | `DES` | | a perpetual | `PERP` on its market | | an earnings date | `ERN` for the company | | a CPI or FOMC alert | `CPI` or `WIRP` | | an economic calendar event | `ECO` on its country | | a catalyst rule | `CATL` (on its company when it names one) | | a Congress rule | `CG` | | a 13F rule | `13F` on the fund | | a news keyword with no symbol | `SRCH` on the keyword | | options flow on your lists | `FLOW` | | breaking news with no symbol | `FIRST` | **Price alerts** are checked by the running app on every price tick, and it notifies you there. Signed in with Cloud sync on, an alert the app has synced also reaches you with the app closed: - Gloom Cloud pushes it to the phone app when one is registered. - It emails it (verified email address, once per arming, up to 20 a day) once no app has synced your account for about 15 minutes. - Signed out, nothing outside the running app notifies you. - The symbol is read as `quote` reads it, so `USDMXN` and `USD/MXN` are the one pair `USDMXN=X`. A symbol that quotes nothing is refused with the nearest listing (`did you mean AAPL`), and a bare code kept on a listing abroad names it. - A bare coin ticker whose listing is a fund says so as `quote` does (`BTC is Grayscale Bitcoin Mini Trust ETF, not bitcoin. For bitcoin use BTC-USD.`), and so do `fn` reports such as `fn OPX BTC`. - A target more than 10 times the last price, or under a tenth of it, is refused, in **Add Alert** too (`alerts add btc above 85000` is bitcoin's price typed on the fund). - A price reads the same in `alerts add`, the `SA` shortcut and the **Add Alert** form: `81000`, `81,000.50`, `1.350,5` and `81k` or `1.5m` (a thousand and a million). A comma before exactly three digits (`81,000`) could be thousands or a decimal comma, so it names both readings and adds nothing; text that is no number is refused with the format to type (`type 81000 or 81k`). - If saved price alerts cannot be read, the app and CLI leave the data unchanged and price checks pause until it is repaired. The pane and `gloom alerts list` show the read error, and event alerts stay usable. - On **Prices**, Enter opens an alert in full: its state, the price and how far it is from the level, and when its quote was checked. An alert that could not get a quote shows that in red on its row, and its detail says why. `m` re-arms an alert that went off. ### Alerts before earnings and economic releases To watch a position through a scheduled event, alert a number of days before it. In `ALRT`, open **Events**, click **add event** (or run **Add Event Alert**) and pick **Earnings date** with a US-listed symbol, or **Macro event** with the CPI release or the FOMC decision, then the days before (1 to 14, 1 by default). Any other release in the economic calendar is added from the shell, by name. An earnings alert can instead wait for the report: pick **When results are out** under **Alert**, which is what `n` in `ERN` sets. From the shell: ```bash gloom alerts add CRWV earnings --days 3 gloom alerts add CRWV earnings results gloom alerts add CPI --days 1 gloom alerts add FOMC gloom alerts add "NBS PMI" gloom alerts add CN PMI gloom alerts add "Industrial Profits" --country CN --days 2 ``` The next date comes from `ERN`, the BLS release calendar behind `CPI`, the Fed meeting calendar behind `WIRP` and, for any other release, the economic calendar `ECO` and `econ` list. A symbol with no upcoming earnings date, or an event with no known next date, gets no alert. The **Events** tab and `alerts list` show each alert's next event date and state. **A release by name.** `alerts add [--country ] [--days ]` takes any release in the economic calendar, as `econ` names it: - Some of its words are enough: `NBS PMI` is `NBS Manufacturing PMI`, a word's start (`manuf`) or a name's initials (`NFP`) read too, and `CPI` reads as a country's `Inflation Rate YoY`. Of several releases the words name, the highest impact wins, then the shortest name; the reply says what it read the words as and lists the others. - A country code first (`CN PMI`) or `--country` (`CN`, `UK`, a region such as `G7`) narrows it. A name listed in several countries without one is refused with the best of each, and a name nothing matches with the nearest names (`Did you mean NBS Manufacturing PMI (CN)?`). - `CPI` and `FOMC`, alone or in the US, stay the CPI and FOMC alerts above. - A release the calendar lists only in the past is followed once its next date is listed, about two weeks ahead. - While the app runs it checks the dates every 15 minutes and notifies once when the lead time is reached ("CRWV earnings in 3 days, Mon, Nov 9", counted in New York calendar days). An app that was closed that day notifies when it next runs, up to the event day. - A release from the economic calendar counts in UTC days, as the calendar lists it, and gives its time ("NBS Manufacturing PMI (CN) in 21 hours, Sat, Oct 31, 01:30 UTC"); an all-day event (a plenum, an election) gives its day. - A release, CPI and FOMC included, then notifies once more with its figures when they print ("NBS Manufacturing PMI (CN) 50.3 vs 50.0 expected, prior 50.1"), asking every minute for half an hour after the release time. Figures printed before the alert was set, or more than 12 hours before the app next runs, are not sent. An event with no figures (a plenum) alerts only before it. - An alert for results goes off once the report's actual EPS is in `ERN`, on the report day or usually that evening for a report after the close ("CRWV reported EPS 0.12 vs 0.10 expected (+20.0%)"). It waits up to 3 days past the date for a late figure, then follows the next report. - The alert then reads **Alerted** until the event passes and arms itself for the next date. Re-arm (`m`, or `gloom alerts rearm `) sends it again for the same event, and `gloom alerts delete ` removes it. - Earnings alerts also reach the phone app like the other market alerts, once per report and never on the day itself. CPI, FOMC and other economic release alerts notify in the running app only. `gloom fn ALRT` lists your price alerts, `--tab events` your event alerts with their event date, lead time and state, and `--tab history` the alerts that went off. `gloom shot ALRT --tab events` draws that tab. **Alert history.** Every alert the app fires (price, IV level, earnings, CPI, FOMC and other economic releases) is kept on this device, the last 1,000, with when it went off, the rule, the figure and the quote time and feed. **History** and `fn ALRT --tab history` list that log with no sign-in. Signed in, they also merge in the alerts Gloom Cloud delivered to your phone or email over the last 90 days, and the Via column says which sent each: this app, Gloom Cloud or both. ## Live prices and refresh cadence Prices come from one shared stream, and a symbol shown in several panes is subscribed once. Rows on screen and the selected symbol update about 10 times a second, everything else about once a second. Minimizing or hiding the app pauses streams and polling, and plans that cap streamed symbols spend them on the rows in view. What moves while you watch: - **Portfolios and watchlists:** price, change, volume, market value, P&L and weight. MCAP, P/E, FWD P/E and DIV% are repriced from the live price when the per-share figure behind each is on the quote's currency basis. 52W% counts today's range, and TARGET% uses the live price when the target is in the listing's currency. Broker account totals, Net Liq and P&L move with the positions' quotes. - After the regular close, LAST, CHG and CHG% hold the official close and its move, while EXT% follows the extended-hours print from that close (market value, DAY and P&L keep the live price). In the pre-market the row holds the last session the same way when the quote carries its close and move, otherwise LAST and EXT% are the pre-market print. `DES` uses the same rules. - `WEI`, `FUT`, `BI`/`SP`, `FXC`, `EQS` rows, `CRYP`, the header SPY chip and market state, and price alerts (which trigger on the tick that crosses). After the close `BI`, `MOST`'s lists and `EQS` hold the regular close and only their extended-hours column moves (see [Company Research](#company-research)). - **Charts**, including the research Chart tab: the forming bar takes each quote's high, low, close and volume. A daily, weekly or monthly bar is the regular session's: after the close it holds at the official close, the close `gloom history` and `portfolio show --close` give. Intraday bars and the extended-hours view of a US listing keep the extended prints. - `OMON`: Last, volume, IV and Greeks stream during the regular session, and a real-time chain reloads every 15 seconds. `OVDV` reloads a real-time surface every 15 seconds in session, `HVG` re-reads its ATM IV every minute, `VOLS` and the `VIX` curve stream index levels, and `CTM` and `WIRP` refresh delayed contract quotes every minute while Globex trades. News panes refresh every two minutes while the app is visible (a hidden browser tab falls back to the configured interval, which still feeds breaking-news notifications). `VF` toggles value flashing: a changed price dims for 300 ms. ## CLI Running `gloom` with no arguments launches the terminal UI. Normal commands run headless. Use `gloom launch-ui` when a script should explicitly open the UI. ### Output and flags Human-readable output is the default: tables fit the terminal width, and a single result prints as aligned label and value lines. Piped text keeps every cell whole. - `--json`, `--csv` and `--ndjson` give structured output, which is how to export anything (`gloom history LMT --csv > lmt.csv`). JSON uses the richest model and includes display-column metadata. CSV and NDJSON use the tabular rows. - Common global flags: `--limit`, `--tail`, `--width`, `--refresh`, `--quiet`, `--no-color`, `--plain`, `--no-plain`, `--dry-run`, `--yes`. **Plain output.** `--plain` prints text for a screen reader or very large text. It is on without the flag when `NO_COLOR` is set to a non-empty value (an empty `NO_COLOR` is the same as unset) or the output is not a terminal (piped or redirected). `--no-plain` turns it off, piped or not. - Tables have no rule under their header and keep the same columns from one query to the next: an empty cell reads `—` (`econ` prints Actual and Forecast before they are out). - Arrows are words in tables and in the lines the CLI writes itself: a sort mark after a header reads `(sorted descending)` instead of `▼`, and `→` reads `to`. Free text outside a table, such as a note or an answer, prints as it is. - Colour is off unless `--color` asks for it. `--json`, `--csv` and `--ndjson` are the same with or without it. Cboe's Treasury yield indices (`^IRX`, `^FVX`, `^TNX`, `^TYX`) print their level in percent (`5.24%`) and their change in basis points (`+1.3bp`) under a `Chg` header. `--json` adds `unit` and `changeBasisPoints` to their rows and keeps the percent change. ### Fitting tables to a width `--width ` fits text tables, help and notes to n columns, in a terminal or piped (`gloom quote AAPL TSLA NVDA MSFT --width 80`). Without it a terminal's own width applies and piped output is not fitted. - A table gives up its least useful columns first (`compare` drops Cur, Volume and Day Range). `quote` drops none: at 80 or 100 columns it moves Updated, Feed, Cur and Chg Basis onto a labelled line under each row (`Feed delayed Updated 2026-10-23 15:40 UTC`). No cell is cut short: text wraps, and columns that still do not fit move onto indented lines under each row. - The function list of `catalog` is the one table that cuts (a description ends in `…`, and `catalog ` prints it whole). `shot` has its own `--width`, in pixels. The layout is 720 to 2400 wide and 360 to 1800 tall (`--height`), and the PNG is drawn at twice that size, so the default 1280 by 720 writes 2560 by 1440. - A fixed board such as `FUT` grows until every row shows (up to 1800) unless you give `--height`. - A size outside the limits is drawn at the nearest one, with a warning: `--width 80 is below the 720 minimum, so the capture used 720 and the PNG is 1440 px wide.` ### Typed symbols **Not a ticker.** A symbol that no listing carries (a typo, or a word that names no company) ends in ``Not a ticker: APPLEX. Try `gloom search Applex`.`` on `quote`, `compare`, `history`, `ticker` and the `fn` reports (an `fn` report of one symbol that finds nothing, such as `fn RDCF Palantir`, fails with that line too). - A one-word company name is read the way a longer one is: `quote Apple` is AAPL, with `Read "Apple" as AAPL:NASDAQ (Apple Inc.).` A real ticker always wins over a name (`quote GOLD` is GOLD). A word many names share is read only as search's top result or a listing named exactly that word, never as any listing that merely has the word in its name. A coin's name (`bitcoin`) keeps its coin hint (`BTC-USD`), and a subject such as `carbon` or `freight` keeps its search hint. - `notes show`, `notes set` and `notes delete` pick the same note. A note already saved under the word as typed comes first. Otherwise the symbol is read as `quote` reads it: `notes set Petrobras "…"` saves the note for PBR. `notes set` fails only when the word is definitely not a ticker. Offline, with the data service down, for a symbol with no quote, or with `--dry-run`, the note goes under the symbol as typed. - A FRED series id points to the command that prints it: ``Not a ticker: DFEDTARU. Try `gloom fred DFEDTARU`.`` - A US Treasury yield typed as a ticker (`US10Y`, `UST10Y`, `US10YR`, `US2Y`, `US30Y`, `10Y`, `TNX`) names the commands that have it: ``Not a ticker: US10Y. Try `gloom quote ^TNX`, `gloom fred DGS10` or `gloom yield-curve` for the US 10-year Treasury yield.`` `search` and `catalog` answer those spellings, or `"10 year yield"`, the same way. **Pairs and share classes** - A coin pair written the way crypto exchanges write it, `BTC/USD`, is the coin `BTC-USD`. A currency pair such as `EUR/USD` stays a currency pair. - Every spelling of a currency pair is one listing: `USD/NGN`, `usd/ngn`, `USDNGN=X` and `USDNGN:CCY` are all `USDNGN=X`, and `JPY=X` is `USDJPY=X`. `USD-NGN` and `USDNGN` read the same unless a security is listed under those letters (`MNT-USD` stays the coin). - A share class written `BRK.B` or `BRK-B`, the listing named with its exchange (`BRK.B:NYSE`) and the one you saved are one listing. - A symbol written like a pair that is not a ticker names the nearest listing: ``Not a ticker: USD_NGN. Did you mean USDNGN=X (US Dollar/Nigerian Naira)?`` **Stopped listings.** A listing whose quote stopped more than half a year ago says so under the table: `TWTR: no longer trading since 2022-10-27 (last price $53.86)`. - `watchlist add` and `portfolio add` refuse it, and `history`, `options`, `fn HIVG` and `fn VCA` say `TWTR stopped trading 2022-10-27; no history or options served`. - `search TWTR` lists it under No Longer Trading (`--json` adds `lastTraded`, `lastPrice` and `note`). **A coin ticker that is also a fund.** A bare coin ticker that reads as a fund named for the coin says so on `quote`, `ticker`, `watchlist add`, `portfolio add`, `position set` and `target set`: `ETH is Grayscale Ethereum Staking Mini ETF, not ethereum. For ethereum use ETH-USD.` - A coin ticker that several companies list ends its list of listings the same way (`SOL is Solvay SA, Washington H. Soul Pattinson and Company Limited or another company, not solana. For solana use SOL-USD.`). A company that only shares the letters (`LINK`, Interlink Electronics) and a listing named on purpose (`ETH:ARCA`, `--exchange ARCA`) get no note. - `--json` carries the note in `warnings`, in an error's `details`, and in each row's `hint`. **Names.** A listing goes by the name its own quote gives, in every command, including portfolio and watchlist rows. ### Symbol changes A US symbol that changed says so in one line. - **Something else lists there now.** `quote`, `compare`, `history`, `options`, `search`, `fn HIVG`, `fn VCA`, `watchlist add` and `portfolio add` print `FB now lists ProShares S&P 500 Dynamic Daily Buffer ETF; Meta Platforms trades as META (changed 2022-06-09)`. The options functions say that line for a fund with no options, or a listing that stopped (`TWTR: Delisted Oct 27, 2022`), instead of a chain error. - **Nothing lists there any more.** The line reads `HFC became DINO on 2022-03-15`, and an add that finds no listing ends with it. A company that moved more than once is followed to where it trades now (`TRCH became MMAT on 2021-07-06, then MMATQ on 2024-08-21`). - **No data of its own.** The old symbol has none: `history`, `options`, `ticker` and one-ticker `fn` functions (`fn HIVG HFC`) end in that line with the command for the new symbol: ``HFC became DINO on 2022-03-15: `gloom history DINO` ``. - `quote` and `compare` keep the old line's last price and print ``RDS-A became SHEL on 2022-01-31: `gloom quote SHEL` `` above it. - The `--json` error has `code` `ticker_moved`, `tickerChange` and `retry`. - **The new symbol.** The symbol a company renamed into (`META`, `XYZ`, `METV`) prints nothing extra, but its `history` from before the change says so: `Includes FB-era bars: META was FB until 2022-06-09`. In `--json`, each row's `tickerChange` carries `kind`, `note`, `changes` and, for a company that moved, `tradesAs`, `issuer` and `listed`. A renamed company's new symbol has `kind` `formerly` and the symbol it had before (`METV was META until 2022-01-31`). In the app, a pane that shows one ticker (Ticker Research, a one-security chart, HIVG) shows `RDS-A became SHEL on 2022-01-31.` and an Open SHEL button (Enter, or the pane menu). The quote monitor and lists keep the old line's last price, read STALE, and an add row says where a moved company trades now (`Meta Platforms trades as META`). The change history covers US listings from April 2017. ### Perpetuals and futures codes A perpetual futures market works wherever a symbol is typed, as a listing on its venue: `quote binance:BZUSDT`, `watchlist add Energy hyperliquid:xyz:BRENTOIL`, or the saved forms `BZUSDT:BINANCE` and `XYZ-BRENTOIL:HYPERLIQUID`. `search brent` lists the Brent contracts, and a perpetual row in a watchlist or portfolio opens `PERP`. See [Perpetual markets](perpetuals.md#in-watchlists-quotes-and-search). The FUT board's codes work wherever a symbol is typed (`quote`, `history`, `ticker`, `alerts`, watchlist and portfolio commands, the command bar). - A code no listed security uses (TTF, ZN, 6E) is its future: `quote TTF` quotes `TTF=F`. - A code a security also uses stays the security's (NG is NovaGold, CL Colgate, ZM Zoom). Its future is the `=F` symbol (`quote NG=F`), and `search NG` lists it right after the security. - `search` and `catalog` say so when no source carries what was asked for, with the nearest listings that do: `search EUA` answers `No EU carbon price (EUA) yet. Proxies: CO2:LSE, KRBN.` ### Limiting rows `--limit ` keeps the first n rows as printed. On a series that runs oldest first, such as `history`, those are the oldest, and text output says `showing the oldest 2 of 252 rows; --tail 2 for the latest`. `--json` carries `metadata.rows` (`shown`, `total`, `kept`). `--tail ` keeps the newest n rows of a dated series (`history`, `fred`, `econ`), in their printed order, and the last n of any other list. The two cannot be combined. `fn` reports fail on either one they do not have. ### The economic calendar (`econ`) `econ` lists the economic calendar from today (UTC), about two weeks ahead. **Dates** - `--from ` starts it on another day. An earlier day lists past events with the figures they were released with (`econ --from 2026-10-12 --country US` reaches the previous week's CPI). When the stored calendar starts after that day, text says `The stored calendar starts ` and `--json` has `metadata.storedFrom`. - With no network or a server error, `econ` lists the current calendar and warns that the stored one could not be read. - `--tail ` without `--from` keeps the last n events of the whole calendar, the past week's too. - When the calendar stops less than a week past its first day, text ends with `No events listed after ` (`--json` carries the last day as `metadata.listedThrough`, and the ECO pane says it in its footer). **Times** - Rows are listed by their UTC day and time, with the weekday in `Day`; a release its publisher times also shows its own clock (`09:00 Sao Paulo`). - An event that takes the whole day (a plenum, an election) reads `All day` in the time column, as does the ECO pane. - `--tz ` adds a column on another clock, named by its city, and `Day` moves beside it to give the weekday on that clock: `econ --country BR --tz America/New_York` shows the IPCA at `08:00` under `New York`, and a release at 01:30 UTC on a Wednesday as `Tue` `21:30`. An all-day event keeps its own day. `--json` has `day`, `viewerDate`, `viewerTime` and `metadata.timeZone`; an unknown zone fails with `Unknown time zone`. - With `config set timezone`, the ECO pane shows the same column for your zone beside `TIME (UTC)` when it is wide enough. **Countries** - `--country` takes the ECO pane's regions (`US`, `G7`, `EU`, `all`) or any country by its ISO two-letter code, several comma separated. `UK` reads as `GB`, and `G7,MX` adds Mexico to the G7. `econ --country TR` lists Türkiye's CPI releases, and `ECO MX,BR` and `fn ECO --country MX,BR` open the pane on the same countries. - `econ --country BR` lists IBGE's IPCA and IPCA-15 as `IPCA CPI m/m` and `IPCA-15 Mid-Month CPI m/m`: the actual and prior from the central bank's SGS series 433 and 7478 once the release time has passed, the forecast where the calendar has a consensus. The series chart as `FRED:BRAIPCAMOM` and `FRED:BRAIPCA15MOM`; `catalog IPCA` finds them. - A national release in the euro area is its member's: the calendar shows the German Ifo as `DE`. The ECB's and the euro area's own releases stay `EU`, and `EU` still lists the members' releases. - A country with nothing in the window says `No scheduled releases for MX in this window.` A code that is no country (`TUR`, `XQ`) fails with `Unknown country`. **Publishers.** A row names who publishes it in the Publisher column (Freddie Mac for the 30-year mortgage rate, the Census Bureau for building permits), and `--json` carries `publisher`, `referencePeriod` (the period it covers: `Sep 2026`, or the week of a weekly figure, `22 Oct 2026`), `source` and `sourceUrl` (the publisher's page); `--csv` has the Publisher column. A row whose listing names no publisher leaves them empty. **Central banks and CPI dates.** The calendar also lists the rate decisions of the central banks `fn CBR` follows (Banxico, Copom, SARB, CBRT, RBI, BoK and the rest), each with the policy rate before it as Prior, and the CPI release dates INEGI (Mexico) and IBGE (Brazil) publish. Those rows add a Local column with the publisher's own clock (`06:00 Mexico City` for INEGI's 12:00 UTC release). `--json` carries `localTime`, `timeZone`, `timeNote`, `priorAsOf`, `referencePeriod`, `source` and `sourceUrl` on them. **After a release time.** Once a high-impact release's time passes with no actual, the app asks Gloom Cloud for the calendar again (after about 15 seconds, then 30, then once a minute for 20 minutes) while ECO is in view or **Notifications** is on in ECO's settings. With Notifications on (off by default) the number also shows in a toast when it prints, even while ECO is closed: `CPI m/m 0.3% vs 0.3%`, the forecast after `vs`. ### Dates, units and time zones **Date options.** A date option takes `2026-10-01`, `1.10.2026` (day first), `Oct 1 2026`, `1 Oct 2026` or `October 1, 2026` (quote it when it has spaces: `econ --from "Oct 1 2026"`). That covers `econ --from`, `fred --start`, `fn CATL --from`, `fn KPIS --as-of`, `fn OVDV --date`, `fn GC --date`, `fn CTM --date`, `fn GIP --session`, `fn EM --period`, `--expiration`, `options --leaps --expiry-from` and a pane's date field. A slashed date is refused with the formats it takes and the date to type: `type --from 2026-10-14 for 14/10/2026.` **Units.** Headless chart text includes a Unit column when a series supplies one, and values keep that unit's scale (`2.7 %` versus `270 bp`). DVD text labels cash growth, CAGR and earnings payout as percentages, while their structured `value` fields stay fractional ratios (`0.03` means 3%), as are its yields (`0.045527`, `4.5527` in a CSV percent column). **Time zones.** CLI text prints every time in UTC with the zone named (`2026-10-09 00:08 UTC`), and a date alone stays a date. JSON and CSV keep the raw ISO or epoch values. `gloom config set timezone Asia/Tokyo` (any IANA zone name) adds your own clock beside every UTC time (`2026-10-09 23:59 UTC (Sat 10 Oct 08:59 Asia/Tokyo)`), and `config set timezone none` goes back to UTC alone. ### Unknown options A command fails on an option it does not take instead of ignoring it. `gloom history AAPL --since 2020-01-01` ends in `Unknown option --since for history.` with the options `history` does take (`--from` and `--to`), and a close match when you mistyped one. - `financials` lists fiscal years, so `gloom financials WFC --quarterly` (or `--period`, `--freq`) points at `fn GF WFC --period quarterly --periods 40` (one metric over time) and `fn FA WFC --period quarterly` (the statements). - A command that takes one symbol or currency fails on a second (`gloom fx NGN ZAR`; write a pair as `fx ZAR/NGN`), and `econ` fails on a country or impact it does not filter by. - Everything after a bare `--` is an argument, never an option. ### `history` `gloom history` serves each range in one bar size, listed by `gloom help history`. **Ranges** - `--range YTD` (any case) is the year's daily bars from the prior year's last close, the one year-to-date returns are measured from (`history LMT --range YTD` starts at 31 Dec 2025). - `--range ALL` reaches back up to 50 years. When the source's first bar is well inside that, a warning says where it starts (`ALL starts 2014-09; the source has no earlier bar` for BTC-USD), or why nothing older is served (`Price history starts 1992-12-01; old-shekel quotes before 1992 are not served.`). - `gloom help history` ends with where long history is. ZAR has daily FRED data from 1980 (`fred DEXSFUS`). NGN, SAR and ILS have no FRED series, daily bars for the last five years (`fn G USDNGN=X --rangePreset 5Y --chartResolution 1d`) and monthly bars only before that (`history USDNGN=X --range ALL`). - `--interval 1s` says `No second or tick bars; 1-minute bars: fn GIP HYG; for a US listing, each trade: fn TAS HYG (a window: --from 10:30 --to 10:35), each quote: fn QR HYG.` (`fn GIP --chartResolution 1s`, `30s` or `tick` and `catalog tick` say the same). **What the output says** - The line under the heading names the currency the prices are in (an FX pair reads `ZAR per USD`, an index `Index points`, a sub-unit `ILA (agorot, 1/100 ILS)`, `Currency unknown` when no source states one), the bar size served, the first and last bar and the bar count. - `--json` carries the same in `metadata` (`currency`, `unit`, `interval`, `firstDate`, `lastDate`, `bars`, `requestedRange`, `asOf`). Every row has `currency`, `unit` (what one price is: `USD`, `index points`, `ZAR per USD`), `interval` and `flag`. - Every `--csv` has one header, whatever the symbol, range or market state: `Date,Open,High,Low,Close,Volume,Flag,Partial,Filled,Unsettled,Volume unit,Volume note,Venue volume,Volume venue,status`, then the [five fixed columns](#what-every-exported-row-says) every export ends with. Prices are plain numbers, `Partial`, `Filled` and `Unsettled` are `true` or `false` on every bar, and `status` says why a row has no prices (`prices left blank: high bars.csv`. - Symbols load eight at a time. A list of more than ten skips the lookups of a bare symbol's other venues, as `quote` does. - The `--csv` header is a single symbol's. Each row names its symbol, its currency and its own symbol's as-of in `symbol_or_series`, `currency_or_unit` and `as_of`. - A symbol with no bars is one row with its reason in `status` (`Not a ticker: ZZZZQQ.`) and a warning on stderr. A list answered from a saved copy ends `couldn't refresh; saved