Ghost Finance Terminal

Ghost Finance Terminal is a CLI-first financial terminal for saved tickers, market data, news, sentiment, insider trading, terminal-native charts, and Orb AI watchlist research.

The project is in early scaffold stage. Watchlist storage and service configuration are implemented. Market data, news, sentiment, insider trading, and chart commands are routed but not connected to live providers yet.

Planning and maintenance notes are tracked in:

FEATURES.md
BUGS.md

Requirements

• Node.js 20+
• npm

Setup

npm install
npm run build

Use As ghost

Link the local package so you can run ghost directly:

npm run link:local

Then run:

ghost watch list
ghost services selected
ghost orb

After changing source files, rebuild:

npm run build

You only need to run npm run link:local again if the package binary mapping changes.

To remove the local command:

npm run unlink:local

Development Mode

You can also run commands without linking:

npm run dev -- watch list

Selected Ticker

Set a default ticker once, then omit the symbol from ticker-based commands:

ghost ticker select AAPL
ghost ticker show
ghost quote
ghost news
ghost sentiment

You can still pass a symbol directly when you want to override the selected ticker:

ghost quote MSFT

Local UI

Start the browser dashboard:

ghost ui

Custom port:

ghost ui --port 4000

Check or stop the tracked dashboard server:

ghost ui status
ghost ui stop

If an older or untracked process is already using the UI port, stop that listener directly:

ghost ui stop --port 3737

Default URL:

http://127.0.0.1:3737

If the requested port is busy, Ghost automatically tries the next available port.

The UI uses the same local JSON storage and service configuration as the CLI.

Watchlist Commands

ghost watch add AAPL
ghost watch add MSFT
ghost watch list
ghost watch remove AAPL

Saved tickers are stored in:

data/watchlist.json

Service Commands

Services are the framework for external APIs that may require API keys or secrets.

ghost services selected
ghost services set <service-id> <secret-key> <value>

Supported services are defined in:

src/core/services/service-registry.ts

Current supported services:

Market Data
  yahoo-finance    https://finance.yahoo.com/    no secret required
  alphavantage    https://www.alphavantage.co/    secret: apiKey

News
  yahoo-finance    https://finance.yahoo.com/    no secret required
  newsapi    https://newsapi.org/    secret: apiKey

Sentiment
  yahoo-finance    https://finance.yahoo.com/    no secret required
  alphavantage    https://www.alphavantage.co/    secret: apiKey

AI Assistant
  gemini    https://ai.google.dev/gemini-api    secret: apiKey

Example Alpha Vantage setup:

ghost services set alphavantage apiKey <your-alpha-vantage-key>
ghost services selected

Example NewsAPI setup:

ghost services set newsapi apiKey <your-newsapi-key>
ghost services selected

Example Gemini setup for Orb:

ghost services set gemini apiKey <your-gemini-api-key>
ghost orb
ghost orb ask "should I trim or add to my current watchlist today?"

Selected services and local credentials are stored in:

data/services.json

Secret values are currently stored as local plaintext JSON. CLI display masks configured secrets, but this should move to an OS keychain before serious use.

News Commands

NewsAPI powers the primary ghost news implementation when configured. If NewsAPI is not configured or a request fails, Ghost falls back to Yahoo Finance news through yahoo-finance2.

Configure it:

ghost services set newsapi apiKey <your-newsapi-key>

Fetch latest articles:

ghost news AAPL
ghost news MSFT

The primary provider uses NewsAPI's /v2/everything endpoint with sortBy=publishedAt, language=en, and X-Api-Key authentication. The fallback uses Yahoo Finance search results. Results are cached in data/cache/news.json using the standard cache retention period.

Sentiment Commands

Alpha Vantage powers the primary ghost sentiment implementation when configured. If Alpha Vantage is not configured or a request fails, Ghost falls back to a conservative headline-derived Yahoo Finance news sentiment score.

Configure it:

ghost services set alphavantage apiKey <your-alpha-vantage-key>

Fetch ticker sentiment:

ghost sentiment AAPL

The primary provider uses Alpha Vantage's NEWS_SENTIMENT function. The fallback uses Yahoo Finance search headlines and a small financial sentiment lexicon. Results are cached in data/cache/sentiment.json.

Orb Commands

Orb is a terminal-only Gemini assistant for the current watchlist. It collects your saved symbols, adds available quote and company metric context, then asks Gemini to act as a financial researcher for daily overviews or direct finance questions.

Configure Gemini:

ghost services set gemini apiKey <your-gemini-api-key>

You can also set GEMINI_API_KEY in your environment. Override the default model with GEMINI_MODEL.

Run the daily overview:

ghost orb

Ask a question:

ghost orb ask "compare my watchlist by valuation risk"
ghost orb "compare my watchlist by valuation risk"

Quote Commands

Yahoo Finance powers no-key financial snapshots with quote, valuation, revenue, profile, company metrics, latest news fallback, and derived sentiment fallback. Alpha Vantage remains available when configured.

ghost quote AAPL

The quote command shows price, daily change, daily change percent, latest market time, and available company metrics such as market cap, enterprise value, revenue, revenue growth, margins, P/E, price/sales, price/book, debt/equity, sector, industry, and website. The UI Snapshot and Financials widgets use the same endpoint.

Yahoo Finance is provided through the yahoo-finance2 package and does not require an API key.

Planned Commands

These commands exist but are not implemented yet:

ghost orb
ghost chart --range 6m
ghost insiders
ghost dashboard

Local Data And Cache

By default, runtime data is stored under data/.

data/
  watchlist.json
  services.json
  preferences.json
  cache/
    market-data.json
    news.json
    sentiment.json
    insiders.json

Cache records expire after 7 days by default. You can override this with:

GHOST_CACHE_RETENTION_HOURS=720 ghost services selected

You can also change the data directory:

GHOST_DATA_DIR=/path/to/data ghost watch list

The UI also lets you choose the cache retention period:

24hr
7 days
30 days

The selected option is stored in data/preferences.json and controls when provider endpoints are called again.

Quality Checks

npm run typecheck
npm run build

Project Layout

src/
  cli/          Command routing and terminal renderers.
  core/         Domain contracts for watchlists, services, providers, and charts.
  providers/    External API adapter factories.
  storage/      JSON-backed local repositories.
  config/       Environment configuration.
  shared/       Cross-cutting helpers and errors.
docs/           Architecture notes.
data/           Local runtime data.