mpal-cli

mpal helps you review stock ideas and portfolio changes before you act. It turns Marketpal data, model output, rule checks, and your final decision into clear local records you can inspect later.

It is not a broker, not an autonomous trader, and cannot place live orders.

New here? Run the one-command tour:

mpal tour
mpal demo run --json

It prints a short first-run checklist, explains the main terms in plain English, and points to the no-key demo files in examples/demo/.

Boundary

This repo is for research, validation, and record keeping. It does not provide financial product advice, personal advice, investment advice, tax advice, or legal advice.

mpal produces review artifacts from user-supplied inputs and Marketpal API data. Those artifacts are not order instructions and do not recommend that any person buy, sell, hold, trim, reduce, or exit any financial product.

Use with retail clients only if you are appropriately licensed or authorised and perform any required suitability, disclosure, and compliance checks outside this repository.

Positioning

General chat agents are useful for brainstorming and plain-English research. mpal-cli is for the repeatable part of a portfolio review: gather the same Marketpal evidence, check the same rules, save the same decision record, and make it easy to look back later.

For a retail investor, the useful question is simple: "What did the model say, what did I decide, and did my plan pass the rules?" mpal-cli keeps those answers in local artifacts instead of leaving them buried in chat history.

Dimension	General financial agent	mpal-cli
Primary job	Ideas, explanations, and broad research	Repeatable review records
Interaction style	Open-ended chat	Commands and saved artifacts
Portfolio rules	Talks about guidelines	Checks cash, size, and risk rules on a concrete plan
Evidence context	Summarizes sources	Packages Marketpal data, model output, and recent events
Accountability	Usually a chat answer	Records model output, rule-check status, human decisions, and outcomes
Agent integration	Depends on the agent environment	Ships CLI plus Codex/Claude plugin workflow support

Quick Start

Install the CLI and MCP server:

go install github.com/revrost/mpal-cli/cmd/mpal@latest
go install github.com/revrost/mpal-cli/cmd/mpal-mcp@latest

Run the deterministic fixture demo first. It does not require MPAL_API_KEY and never calls the live MarketPal API:

mpal tour
mpal demo run --json
mpal demo report
mpal demo journal --json

Then set an API key for API-backed commands:

export MPAL_API_KEY=mpal_...
mpal doctor --json
mpal capabilities --json
mpal strategy list --json

For agent setup, install the plugin and ask:

Run the Marketpal onboarding skill and report the first-run checklist.

Codex:

codex plugin marketplace add revrost/mpal-cli --ref main

Then open /plugins, choose Marketpal Plugins, and install marketpal.

Claude Code:

claude plugin marketplace add revrost/mpal-cli
claude plugin install marketpal@marketpal-plugins

Simplest Human Workflow

Use Marketpal as a review system, not as a trading bot. The normal human loop is:

set up once
-> run a strategy review
-> inspect evidence and DD
-> validate the final human plan
-> journal what the model said vs what you did
-> later journal the outcome

In plain English:

• A strategy review is the model's first pass at what looks interesting.
• A decision gate is the evidence packet you read before accepting or changing that first pass.
• Validation checks whether your concrete plan fits the cash, position-size, and risk rules.
• A config hash is a fingerprint for the exact strategy settings used.
• Journal finalization saves what you actually decided after reviewing the model output.
• A human overlay is your change to the model's first pass: for example, veto, resize, delay, or substitute a trade.

For the full professional workflow and field-level details, see docs/MARKETPAL_REVIEW_WORKFLOW.md.

Which skill should I start with?

Start with marketpal-onboarding when you are installing Marketpal, checking a fresh repo, wiring MCP/plugin tools, setting MPAL_API_KEY, smoke-testing mpal, or confirming approved strategy configs.

Use marketpal-trader for the actual weekly or monthly review. This is the main human-in-the-loop workflow: it runs the baseline strategy, reads the decision gate, checks recent events, applies portfolio policy, validates any override, and journals the final reviewed action.

Use portfolio-review when you want a whole-portfolio or engine-sleeve risk review rather than an immediate trade packet: sleeve drift, concentration, return-target feasibility, thesis buckets, trim/exit candidates, cleanup focus, and durable portfolio rules. It should route executable buy/sell packets back through marketpal-trader.

Use equity-dd-analyst when you want deeper public-equity DD on a narrowed set of names, a thematic comparison, or a source-backed investment memo. In the normal workflow, run the strategy review first, then deepen DD on the proposed trades, alternates, or user-requested tickers that still look relevant.

Use jeremy-lefebvre-equity-analyst when you want a plainspoken, retail-investor stock view inspired by Financial Education-style YouTube analysis: high-conviction but source-backed business quality, growth, valuation, sentiment, catalysts, and bull/bear cases. It must not impersonate Jeremy or provide personal financial advice.

First-time setup

1. Install mpal and mpal-mcp.
2. Run the no-key demo:

mpal demo run --json
mpal demo report
mpal demo journal --json

3. Set MPAL_API_KEY in the same shell or app environment that runs the agent before using API-backed commands.
4. Install the Codex or Claude Code plugin if you want skill-guided reviews.
5. Run:

mpal doctor --json

Use mpal doctor --skip-api --json for a local-only check, or mpal doctor --strict --json in CI when missing required setup should return a non-zero exit code.

6. Ask your agent:

Run the Marketpal onboarding skill and report the first-run checklist.

7. Optional but recommended: create a private portfolio policy at:

~/.marketpal/portfolio-policy.md

That file is where you describe sleeves, fixed/core holdings, contribution rules, high-conviction holdings, review cadence, and whether reviews should be full-portfolio or engine-only. Keep private holdings out of repo-tracked files.

Normal weekly or monthly review

Ask your agent something like:

Use the Marketpal trader skill to run my weekly engine review with
best_weekly_swing_v1. Use my private portfolio policy if available. Show the
baseline, decision gate, alternates, validation result, and journal the final
review.

For a slower monthly review:

Use the Marketpal trader skill to run my monthly swing review with
best_monthly_swing_v1. Separate the raw model plan from my final human action
in the journal.

The trader workflow should do this:

1. Load ~/.marketpal/portfolio-policy.md when present.
2. Choose an approved strategy config with mpal strategy list/show.
3. Run the baseline with mpal strategy run; the command auto-journals the deterministic first pass and returns journal_entry_id.
4. Pull recent source-backed context with mpal ticker events.
5. Read the deterministic evidence packet with mpal decision gate.
6. Explain model result, executable result, sizing, warnings, and alternates.
7. Validate the baseline or any human override with mpal portfolio validate.
8. Generate the deterministic HTML first pass with mpal report <journal_entry_id>.
9. Finalize the same journal entry with mpal journal finalize after the human decision.

Portfolio risk review

Use this when the question is "how risky is the portfolio?", "what should I focus on next?", "do my holdings match my thesis?", or "what are my trim/exit rules?" rather than "what should I trade today?"

Use the portfolio review skill to review my current portfolio against my private
policy and return target. Show sleeve drift, theme concentration, risk score,
trim/exit candidates, and next review triggers. Keep private artifacts outside
repo-tracked paths.

The portfolio review workflow should do this:

1. Pull the current portfolio snapshot and recent transactions into a private artifact path.
2. Load ~/.marketpal/portfolio-policy.md when present.
3. Map holdings to sleeves and thesis buckets.
4. Reconcile weights and flag stale/missing data.
5. Translate any return target into required active-sleeve returns.
6. Score portfolio risk, concentration, thesis coherence, and exit readiness.
7. Identify trim, exit, watchlist, and cleanup candidates.
8. Route concrete executable trade packets to marketpal-trader for validation and journaling.

Where DD fits

Use DD after the model has narrowed the field, not before every review. A good prompt is:

Use the equity DD analyst skill on the proposed trades and top alternates from
the latest Marketpal review. Compare financials, scale, valuation, catalysts,
and risks. Keep the conclusion simple and source-backed.

DD can support a human veto, delay, resize, or bounded replacement, but the final changed plan still needs mpal portfolio validate before it is journaled as the reviewed action.

What gets journaled?

Journal one accountable review in two phases:

• mpal strategy run: starts the first-pass SQLite review and records the raw model packet plus per-ticker model read.
• mpal journal finalize: records the final human decision, final validation, and final per-ticker human call.

Use mpal journal start only when importing or manually assembling a review that did not come from mpal strategy run.

This separation lets you measure whether the human overlay helped or hurt the model over time without logging every intermediate command.

Mental model

• mpal strategy run: the raw model packet.
• mpal decision gate: deterministic evidence, sizing, rejections, and alternates from the completed run.
• marketpal-trader: the human portfolio-manager review process.
• portfolio-review: whole-portfolio risk, sleeve, thesis, return-target, cleanup, and trim/exit policy review.
• jeremy-lefebvre-equity-analyst: plainspoken retail stock analysis inspired by Financial Education-style public analysis, without impersonation or advice.
• mpal portfolio validate: checks whether the final concrete plan obeys the strategy and portfolio rules.
• mpal report <journal_entry_id>: renders the deterministic local HTML first pass.
• mpal journal finalize: records the accountable final human decision in the SQLite journal.

The durable SQLite review-journal schema is documented in docs/REVIEW_JOURNAL_SQLITE.md. It stores accountable review decisions, not every intermediate command or cache payload. Data provenance, timestamp semantics, config hashes, freshness fields, local storage, and API-backed fields are documented in docs/DATA_PROVENANCE_AND_AUDIT.md. Model-risk and compliance boundaries are documented in docs/MODEL_RISK_AND_COMPLIANCE.md.

Contributing map

• CLI commands live in internal/cli/.
• MCP tool wrappers live in internal/mcpserver/.
• Core engine, strategy, decision-gate, validation, and journal types live in pkg/mpal/.
• Agent skills live in skills/.
• Longer workflow docs live in docs/.
• Run go test ./... before opening a PR.

Configuration

API-backed commands use MPAL_API_KEY. Optional environment variables:

export MPAL_BASE_URL=https://api.marketpal.ai
export MPAL_REVIEW_JOURNAL=~/.marketpal/mpal.db
# Legacy/general JSONL journal; review decisions use SQLite above.
export MPAL_JOURNAL=~/.marketpal/journal.jsonl

Review decisions use the SQLite path from MPAL_REVIEW_JOURNAL or MPAL_DB.

Private portfolio policy belongs outside the repo:

~/.marketpal/portfolio-policy.md

Agents may use that file to scope a review packet, but should not copy private holdings or dollar amounts into tracked files.

Strategies

Built-in configs:

• best_weekly_swing_v1: default weekly swing review for current hosted capabilities
• best_monthly_swing_v1: default monthly swing review with monthly Markov/Kelly horizon
• portfolio_low_churn_swing_v1: routine full-portfolio review packet
• engine_weekly_swing_v1: weekly return-engine sleeve review packet
• engine_quality_swing_rebuild_v1: manual engine cleanup or rebuild scenario
• engine_quality_value_reversion_v1: engine quality-value pullback review
• portfolio_quality_value_reversion_v1: full-portfolio quality-value pullback review
• active_momentum_weekly_v1: active pure-momentum weekly review for a high-conviction watchlist
• aggressive_momentum_weekly_v1: concentrated pure-momentum weekly review based on the top raw-return search config
• momentum_profile_v1
• momentum_only_v1
• simple_score_v1

Published result examples live in docs/STRATEGY_BACKTEST_RESULTS.md.

Custom configs can live in:

~/.marketpal/strategies/

Strategy configs are YAML and can be checked against schemas/strategy.schema.json. See docs/STRATEGY_CONFIGS.md. Quality-value mean-reversion configs use optional quality_weight, value_weight, and reversion_weight scoring fields; all scoring weights must sum to 1.0. These fields use the local scoring_v2_quality_value_reversion contract and are marked api_compatible: false until the hosted Marketpal API supports the same scoring contract.

config_hash is calculated from the canonical expanded config that is sent to the hosted API, not from the raw YAML bytes. Slim configs using defaults and equivalent fully expanded configs therefore share the same hash.

The full review workflow is in docs/MARKETPAL_REVIEW_WORKFLOW.md. For audit interpretation, also read docs/DATA_PROVENANCE_AND_AUDIT.md.

Core Commands

Inspect capabilities and configs:

mpal doctor --json
mpal capabilities --json
mpal strategy list --json
mpal strategy show --id best_weekly_swing_v1 --json
mpal strategy validate --config strategies/best_weekly_swing_v1.yaml --json

Read Marketpal data:

mpal portfolio snapshot --json
mpal watchlist get --json
mpal ticker profile --tickers AAPL,MSFT,NVDA --date 2026-05-10 --json
mpal ticker events --tickers AAPL,MSFT,NVDA --days 14 --json
mpal ticker financials --tickers AAPL,MSFT,NVDA --years 6 --include-ttm --json
mpal ticker fundamentals --tickers AAPL,MSFT,NVDA --json
mpal ticker insiders --tickers AAPL,MSFT,NVDA --days 365 --limit 100 --json
mpal ticker ownership --tickers AAPL,MSFT,NVDA --days 365 --limit 100 --json

mpal ticker events is the curated feed for recent source-backed context. It includes price/volume events, filings, ASX announcements, press releases, insider activity, institutional activity, and enriched article/announcement summaries when available.

mpal ticker profile includes server-computed markov and raw_kelly evidence buckets for daily, weekly, and monthly horizons when Marketpal has enough price history. Those fields are sizing evidence only; final fractional Kelly sizing still happens inside the strategy planner and remains clamped by portfolio/risk controls.

mpal ticker fundamentals is a compact profile-backed DD packet. It includes top-level quick metrics (pe, ps, short_interest, revenue_growth_yoy, revenue_growth_yoy_pct), valuation fields (price, market_cap, enterprise_value, pe, forward_pe, pb, ps, ev_to_ebit, ev_to_fcf, fcf_yield, DCF and target-price payloads), estimate fields (forward_eps, trailing_eps, eps_growth, projections, growth pattern, earnings date), and credit fields (debt_to_equity, solvency_ratio, Altman Z-score, latest debt/cash/working-capital fields from stored financials).

Run a strategy review packet:

mpal strategy run \
  --date 2026-05-10 \
  --universe examples/universe.json \
  --portfolio examples/portfolio.json \
  --config strategies/best_weekly_swing_v1.yaml \
  --json

Build an evidence-bound decision gate from a completed strategy run:

mpal decision gate \
  --run tmp/mpal-runs/strategy-run.json \
  --events tmp/mpal-runs/ticker-events.json \
  --config strategies/best_weekly_swing_v1.yaml \
  --alternates 5 \
  --json

Validate, report, and finalize a reviewed packet:

mpal portfolio validate \
  --plan examples/final_plan.json \
  --portfolio examples/portfolio.json \
  --universe examples/universe.json \
  --config strategies/best_weekly_swing_v1.yaml \
  --json

mpal report review_... --json
mpal journal finalize --id review_... --input examples/trade_review_finalize.json --json
mpal journal list --limit 20 --json

For imported reviews that did not come from mpal strategy run, create the first row manually with mpal journal start --input examples/trade_review_start.json --json.

Backtest:

mpal backtest run \
  --start 2025-01-01 \
  --end 2026-01-01 \
  --universe examples/universe.json \
  --config strategies/best_weekly_swing_v1.yaml \
  --json

Review Workflow

A normal research packet is:

1. Choose an approved config with mpal strategy list --json.
2. Inspect it with mpal strategy show --id <strategy-id> --json.
3. Run mpal strategy run with an explicit date, portfolio, universe, and config.
4. Add event context with mpal ticker events.
5. Build the deterministic evidence packet with mpal decision gate --events.
6. Validate any concrete baseline or alternative packet with mpal portfolio validate.
7. Use the returned journal_entry_id to generate the HTML report with mpal report.
8. Finalize that same review with mpal journal finalize after the human decision.

Scheduled or autonomous agent runs should only use approved configs. Agents must not silently modify configs or invent one-off strategy parameters.

MCP

mpal-mcp exposes the same boundary through Model Context Protocol tools. It is a wrapper around the CLI/client logic, not a separate trading system.

Run over stdio:

mpal-mcp

Claude Code:

claude mcp add mpal --env MPAL_API_KEY="$MPAL_API_KEY" -- mpal-mcp

Codex:

codex mcp add mpal -- mpal-mcp

For local source checkout development, use examples/mcp.local.json, which runs go run ./cmd/mpal-mcp.

There is no MCP tool for live order placement.

Agent Rules

mpal strategy run is the source of truth for model output: signals, target weights, proposed model actions, warnings, freshness metadata, strategy ID, strategy version, config hash, and validation result. Signals may include optional markov metadata with trend-state transition probabilities over the strategy rebalance horizon. This metadata is explanatory by default and does not change scoring, planning, or validation unless a strategy explicitly enables the experimental risk.sizing_method: fractional_kelly sizing overlay. That one setting uses conservative internal Kelly defaults; users can tune risk.kelly_fraction for 25%, half Kelly, or another value in (0,1]. Even then, Kelly sizing is only an input and proposed trades remain clamped by the strategy's fixed risk controls, including any limits supplied by risk.profile. Kelly-sized trades include structured sizing audit fields such as kelly_target_weight, final_target_weight, horizon, horizon_bars, binding_constraint, favorable/unfavorable probabilities, and calibration_status. mpal decision gate packages those fields with rejected tickers, alternate signal context, and validation state so an agent can approve, veto, delay, downsize, or propose a validated override without inventing hidden model inputs.

Agents may summarize review packets or construct bounded alternative packets, but must:

• use mpal JSON as source of truth
• not invent model actions outside mpal output
• validate alternative packets with mpal portfolio validate
• use the journal_entry_id returned by mpal strategy run for normal reviews
• use mpal journal start only for manually assembled/imported reviews
• finalize human decisions with mpal journal finalize
• never execute live trades or call broker/order-placement tools

Agents should write concise rationale fields, not private chain-of-thought. mpal-cli journals accountable review decisions and final validation status; it is not a transcript store for every intermediate prompt, tool call, or hidden reasoning trace.

Development

go test ./...
go build ./cmd/mpal ./cmd/mpal-mcp

Generated ConnectRPC code is checked in. If proto/marketpal/v1/mpal.proto changes, regenerate from the repo root:

buf generate

Plugin and registry distribution notes live in PLUGIN_DISTRIBUTION.md.