pp-yahoo-finance

SKILL.md

Yahoo Finance — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the yahoo-finance-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:
npx -y @mvanhorn/printing-press install yahoo-finance --cli-only

Verify: yahoo-finance-pp-cli --version

Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):
go install github.com/mvanhorn/printing-press-library/library/commerce/yahoo-finance/cmd/yahoo-finance-pp-cli@latest

If --version reports "command not found" after install, the install step did not put the binary on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Use this CLI when the user asks about:

stock, ETF, or fund quotes

chart history or price ranges

fundamentals or quote summary modules

options chains or simple moneyness filtering

trending symbols or predefined market screeners

ticker search and autocomplete

local watchlists

portfolio cost basis and unrealized P&L

Do not use it when the user specifically needs:

real-time streaming tick data

exchange-grade paid data feeds

broker/account actions like order entry

Best Command Mapping

"How is AAPL doing?" → yahoo-finance-pp-cli quote --symbols AAPL --agent

"Give me a deeper view on Microsoft" → yahoo-finance-pp-cli quote summary MSFT --agent

"Show me NVDA for the last year" → yahoo-finance-pp-cli chart NVDA --range 1y --interval 1wk --agent

"What are the top gainers today?" → yahoo-finance-pp-cli screener --scr-ids day_gainers --agent

"What is trending in the US?" → yahoo-finance-pp-cli trending US --agent

"Track my portfolio" → yahoo-finance-pp-cli portfolio perf --agent

"Compare AAPL, MSFT, and NVDA" → yahoo-finance-pp-cli compare AAPL MSFT NVDA --agent

"Show me SPY options expiring soon" → yahoo-finance-pp-cli options-chain SPY --max-dte 45 --agent

Unique Capabilities

watchlist

Save named ticker groups locally for reuse across commands.

yahoo-finance-pp-cli watchlist create tech
yahoo-finance-pp-cli watchlist add tech AAPL MSFT NVDA GOOG

portfolio

Track local lots with purchase date and cost basis, then join them with live quotes.

yahoo-finance-pp-cli portfolio add AAPL 50 185.50 --purchased 2024-06-15
yahoo-finance-pp-cli portfolio perf --agent
yahoo-finance-pp-cli portfolio gains --agent

digest

Summarize a watchlist into biggest gainers and losers.

yahoo-finance-pp-cli digest --watchlist tech --agent

compare

Show a normalized multi-symbol comparison.

yahoo-finance-pp-cli compare AAPL MSFT GOOG NVDA --agent

sparkline

Render a compact terminal sparkline from recent chart data.

yahoo-finance-pp-cli sparkline AAPL --range 3mo

sql

Run SQL directly against the local Yahoo/watchlist/portfolio database.

yahoo-finance-pp-cli sql "SELECT watchlist, COUNT(*) FROM watchlist_members GROUP BY watchlist" --agent

fx

Convert currencies without manually building Yahoo FX pair symbols.

yahoo-finance-pp-cli fx USD EUR --amount 100 --agent

options-chain

Filter Yahoo's raw chain into a usable options view by moneyness and DTE.

yahoo-finance-pp-cli options-chain AAPL --moneyness otm --max-dte 45 --type calls --agent

auth login-chrome

Import a browser session when Yahoo blocks the automatic crumb bootstrap from the current IP.

yahoo-finance-pp-cli auth login-chrome --cookies ~/yahoo-cookies.json --crumb abc123

Command Reference

Market data:

yahoo-finance-pp-cli quote --symbols AAPL,MSFT

yahoo-finance-pp-cli quote summary AAPL

yahoo-finance-pp-cli chart AAPL --range 1mo --interval 1d

yahoo-finance-pp-cli fundamentals AAPL --type annualTotalRevenue

yahoo-finance-pp-cli insights --symbol AAPL

yahoo-finance-pp-cli options AAPL

yahoo-finance-pp-cli recommendations AAPL

yahoo-finance-pp-cli screener --scr-ids day_gainers

yahoo-finance-pp-cli trending US

yahoo-finance-pp-cli search "apple"

yahoo-finance-pp-cli autocomplete --query appl

Local-state and derived workflows:

yahoo-finance-pp-cli watchlist create|add|remove|list|show|delete

yahoo-finance-pp-cli portfolio add|list|remove|perf|gains

yahoo-finance-pp-cli digest

yahoo-finance-pp-cli compare

yahoo-finance-pp-cli sparkline

yahoo-finance-pp-cli sql

yahoo-finance-pp-cli fx

yahoo-finance-pp-cli options-chain

Utilities:

yahoo-finance-pp-cli sync

yahoo-finance-pp-cli workflow archive

yahoo-finance-pp-cli workflow status

yahoo-finance-pp-cli export

yahoo-finance-pp-cli import

yahoo-finance-pp-cli doctor

yahoo-finance-pp-cli auth status

yahoo-finance-pp-cli auth logout

yahoo-finance-pp-cli auth login-chrome

Practical Recipes

Morning briefing over a watchlist

yahoo-finance-pp-cli watchlist create tech
yahoo-finance-pp-cli watchlist add tech AAPL MSFT NVDA GOOG META
yahoo-finance-pp-cli digest --watchlist tech --agent

Track a real portfolio with cost basis

yahoo-finance-pp-cli portfolio add AAPL 50 185.50 --purchased 2024-06-15
yahoo-finance-pp-cli portfolio add MSFT 20 340.00 --purchased 2024-03-01
yahoo-finance-pp-cli portfolio perf --agent
yahoo-finance-pp-cli portfolio gains --agent

Compare several large-cap names

yahoo-finance-pp-cli compare AAPL MSFT NVDA GOOG --agent

Fallback when Yahoo blocks your IP

yahoo-finance-pp-cli auth login-chrome --cookies ~/yahoo-cookies.json --crumb abc123
yahoo-finance-pp-cli doctor

Session Model

Yahoo Finance uses a crumb/cookie session model, not an API key model.

first live request: the CLI tries to bootstrap the session automatically

if Yahoo blocks that bootstrap with HTTP 429: use auth login-chrome

inspect cached state: auth status

clear a bad cached session: auth logout

Agent Mode

Add --agent when you want machine-oriented output.

It expands to:

--json

--compact

--no-input

--no-color

--yes

Useful companion flags:

--select <fields>

--dry-run

--no-cache

--data-source auto|live|local

--rate-limit <n>

Filtering output

--select accepts dotted paths to descend into nested responses; arrays traverse element-wise:

yahoo-finance-pp-cli <command> --agent --select id,name
yahoo-finance-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

Response envelope

Data-layer commands wrap output in {"meta": {...}, "results": <data>}. Parse .results for data and .meta.source to know whether it's live or local. The N results (live) summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.

Exit Codes

Code
Meaning

0
Success

2
Usage error

3
Resource not found

4
Session/auth-style error

5
API error

7
Rate limited

10
Config error

Argument Parsing

Given $ARGUMENTS:

Empty, help, or --help → run yahoo-finance-pp-cli --help

install → install CLI

install mcp → install MCP server

Anything else → map the user request to the best command above and run it with --agent

MCP Server Installation

go install github.com/mvanhorn/printing-press-library/library/commerce/yahoo-finance/cmd/yahoo-finance-pp-mcp@latest
claude mcp add yahoo-finance yahoo-finance-pp-mcp

Direct Use

Check whether yahoo-finance-pp-cli is installed.

If not installed, offer CLI installation.

Choose the command that matches the user's intent most directly.

Run with --agent unless the user explicitly wants human-formatted output.

If Yahoo is rate-limiting this machine, guide the user to auth login-chrome.

Agent Workflow Features

This CLI exposes three shared agent-workflow capabilities patched in from cli-printing-press PR #218.

Named profiles

Persist a set of flags under a name and reuse them across invocations.

# Save the current non-default flags as a named profile
yahoo-finance-pp-cli profile save <name>

# Use a profile — overlays its values onto any flag you don't set explicitly
yahoo-finance-pp-cli --profile <name> <command>

# List / inspect / remove
yahoo-finance-pp-cli profile list
yahoo-finance-pp-cli profile show <name>
yahoo-finance-pp-cli profile delete <name> --yes

Flag precedence: explicit flag > env var > profile > default.

--deliver

Route command output to a sink other than stdout. Useful when an agent needs to hand a result to a file, a webhook, or another process without plumbing.

yahoo-finance-pp-cli <command> --deliver file:/path/to/out.json
yahoo-finance-pp-cli <command> --deliver webhook:https://hooks.example/in

File sinks write atomically (tmp + rename). Webhook sinks POST application/json (or application/x-ndjson when --compact is set). Unknown schemes produce a structured refusal listing the supported set.

feedback

Record in-band feedback about this CLI from the agent side of the loop. Local-only by default; safe to call without configuration.

yahoo-finance-pp-cli feedback "what surprised you or tripped you up"
yahoo-finance-pp-cli feedback list         # show local entries
yahoo-finance-pp-cli feedback clear --yes  # wipe

Entries append to ~/.yahoo-finance-pp-cli/feedback.jsonl as JSON lines. When YAHOO_FINANCE_FEEDBACK_ENDPOINT is set and either --send is passed or YAHOO_FINANCE_FEEDBACK_AUTO_SEND=true, the entry is also POSTed upstream (non-blocking — local write always succeeds).