Pp Finra

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/other/finra/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

FINRA — Printing Press CLI

Prerequisites: Install the CLI

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

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install finra --cli-only

2. Verify: finra-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/other/finra/cmd/finra-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

FINRA CLI treats the entire ~35-dataset Query API catalog as a live-discoverable surface instead of a hand-curated list, then layers offline SQLite history on top so Reg SHO escalation streaks, TRACE liquidity trends, and 4530 complaint surges become one-command answers instead of manual CSV diffing.

When to Use This CLI

Use this CLI for FINRA Query API data pulls (equity, fixed income, registration/licensing), compliance monitoring rituals (Reg SHO threshold tracking, 4530 complaint surges), and batch CRD validation before filing submissions.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI to submit U4/U5/BR registration filings — Submission API payload schemas are not publicly documented and are not implemented.
• Do not use this CLI for FileX bulk file transfers — that is SFTP/HTTPS/S3 infrastructure outside this CLI's scope.
• Do not use this CLI for real-time push notifications — FINRA's Notification API is poll-based, not a webhook system.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local state that compounds

• regsho threshold-watch — See which symbols just crossed the Reg SHO 5-day threshold escalation point before it triggers a mandatory close-out.

  Pick this over a raw threshold-list pull when you need to know how many consecutive days a symbol has been flagged, not just whether it's flagged today.

  finra-pp-cli regsho threshold-watch --symbol GME --json

• complaints new — See 4530 customer complaint filings for a firm within a recent time window, without re-reading the full history.

  Use this for a quick recent-activity check; use complaints list for the full history or a custom date range.

  finra-pp-cli complaints new --firm 19847 --since 7d --json

• fixedincome health — One snapshot report joining TRACE, Corporate/Agency Debt Market Breadth, and Corporate/Agency Debt Market Sentiment for a time window.

  Use this for a single fixed-income market-condition snapshot instead of four separate dataset pulls stitched together by hand.

  finra-pp-cli fixedincome health --since 7d --json

• trace liquidity — Month-over-month trend in TRACE Monthly Volume trade count and volume for a product category (or market-wide if no category given).

  Use this for a month-over-month volume/trade-count trend for a product category; use 'trace search' for raw monthly aggregate records instead.

  finra-pp-cli trace liquidity --sub-product CORP --since 180d --json

• registration timeline — Full chronological registration-status history for one person, joining Composite Individual, Firm Registration Status History, and Individual Delta records.

  Use this to see how a rep's registration status changed over time; use 'registration individual --crd' for just the current snapshot.

  finra-pp-cli registration timeline --crd 1234567 --json

Agent-native plumbing

• registration validate-batch — Validate many CRDs from a file in one call instead of checking them one at a time.

  Use this before submitting a batch of registration filings to confirm every CRD is currently valid.

  finra-pp-cli registration validate-batch --file crds.csv --json

Command Reference

async — Poll async job status and results for bulk data extracts

• finra-pp-cli async <group> <name> <requestId> — Poll the status and results of an async data request

catalog — Discover available FINRA datasets and their capabilities

• finra-pp-cli catalog — List all available datasets, optionally filtered by group or name

data — Query FINRA dataset records (equity, fixed income, registration, firm, and content datasets)

• finra-pp-cli data get — Get a single dataset record by its primary ID (only for datasets where supportsGetById is true — check via 'catalog')
• finra-pp-cli data list — List/filter dataset records via query parameters
• finra-pp-cli data query — Filter dataset records via a JSON request body (richer filtering than 'data list')

metadata — Inspect field-level schema and partition fields for a dataset

• finra-pp-cli metadata <group> <name> — Get field list, types, and partition fields for a dataset

partitions — List available partition values (typically dates) for incremental sync

• finra-pp-cli partitions <group> <name> — List available partition values for a dataset, used for incremental sync

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

finra-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Track a symbol's Reg SHO escalation

finra-pp-cli regsho threshold-watch --symbol GME --json --select symbol,consecutive_days,escalated

Narrow the streak-tracker output to just the fields that matter for a compliance check.

Fixed-income market snapshot

finra-pp-cli fixedincome health --since 7d --json

One command replaces four separate dataset pulls (TRACE, breadth, sentiment) stitched together by hand.

Recent complaint filings for a firm

finra-pp-cli complaints new --firm 19847 --since 7d --json

Filters 4530 filings to a recent window instead of scanning the full history.

Bulk-validate CRDs before a filing batch

finra-pp-cli registration validate-batch --file crds.csv --json

Turns N one-at-a-time CRD lookups into a single batch call.

TRACE monthly volume trend for a product category

finra-pp-cli trace liquidity --sub-product CORP --since 180d --json --select sub_product,liquidity_trend,avg_trades_per_month

Pairs --json with --select to keep agent output small for a deeply nested trend response.

Auth Setup

FINRA uses OAuth2 client_credentials: your API Client ID and Client Secret (from the FINRA API Console) are exchanged for a short-lived Bearer token. Set FINRA_CLIENT_ID and FINRA_CLIENT_SECRET, then run 'finra-pp-cli auth login' to fetch and cache a token — it refreshes automatically before expiry.

Run finra-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  finra-pp-cli async OTCMARKET REGSHODAILY req-12345 --agent --select id,name,status

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests