ghtraf portfolio CLI subcommand family

[djdarcy]

ghtraf portfolio CLI subcommand family

Parent: Cross-repo engagement radar epic
Milestone: v0.5.0

Goal

Graduate the prototype into proper CLI subcommands following ghtraf's existing patterns.

Subcommands

ghtraf portfolio collect    # Fetch current data, store snapshot, show deltas
ghtraf portfolio show       # Show latest deltas without collecting new data
ghtraf portfolio history    # Show delta trends over time
ghtraf portfolio setup      # One-time setup: create portfolio gist, configure orgs

Design notes

• Follows the register(subparsers, parents) / run(args) pattern from commands/create.py
• May use nested subparsers (portfolio -> collect/show/history/setup) or flags (portfolio --collect)
• Reuses THAC0 output system, gh.py for API calls, gist.py for storage
• --dry-run support via plan-execute pattern (Plan-Execute architecture — trustworthy --dry-run across all subcommands #53)

New flags

--orgs ORG1,ORG2    # Limit to specific orgs (default: all accessible)
--since DATE        # Compare against specific date (default: most recent snapshot)
--format table|json # Output format

Integration with existing commands

• ghtraf list (ghtraf status and ghtraf list — multi-repo visibility from config #37) could show portfolio summary alongside per-repo status
• ghtraf status (ghtraf status and ghtraf list — multi-repo visibility from config #37) could include portfolio delta as a "headlines" section
• Config layer (project_lib — multi-layer config resolution and template rendering #68 project_lib) stores portfolio settings in ~/.ghtraf/config.json

Dependencies

• Prototype (#SUB1) validates the API and UX
• Storage schema (#SUB2) must be finalized
• Plan-execute pattern (Plan-Execute architecture — trustworthy --dry-run across all subcommands #53) for --dry-run support

Analysis

See 2026-03-21__17-57-11__dev-workflow-process_cross-repo-analytics-extend-vs-separate.md