Command-line interface#
Use gpf to solve a case from the shell. The subcommands run studies, inspect
or modify cases, manage version history, and start the review and agent tools.
gpf - CLI interface#
Solve a RAW, RAWX, MATPOWER, OpenDSS, or mixed TOML input.
gpf [-h] [-o [OUTPUT]] [--plain] [--json] [--max-iter MAX_ITER] [--tol TOL]
[--var-limit MODE] [--tap-adjust {on,off}] [--lcc-dc-tap-adjust {on,off}]
[--phase-shift-adjust {on,off}] [--swshunt-adjust {on,off}]
[--area-interchange {off,tie,tie-load}] [--low-voltage-load PU] [-q] [-v]
[--minimal-nr | --no-remote | --no-facts-dc] [--full | --summary] [-V]
input
gpf positional arguments#
input- Input file (RAW, RAWX, .m, .dss, or mixed-system .toml)
gpf options#
-oOUTPUT,--outputOUTPUT- Output file (-o for auto-naming, -o FILE.html/json for specific format)--plain- Force plain text (no colors)--json- Force JSON output--max-iterMAX_ITER- Newton iteration budget for the whole solve (default: 50, or the case file's value when that asks for more)--tolTOL- Convergence tolerance in pu (default: from the case file, else 1e-06)--var-limitMODE- VAR-limit policy:'off'(never enforce),'immediate'(enforce from the first control review), or'automatic'(enforce after the case first converges). Default: file-format aware — .raw/.rawx/.json use'immediate', .m uses'off'(MATPOWER's enforce_q_lims=0).--tap-adjustTAP_ADJUST- AC tap-changer stepping. on (default) / off.--lcc-dc-tap-adjustLCC_DC_TAP_ADJUST- LCC HVDC TAPR/TAPI stepping. on (default) / off.--phase-shift-adjustPHASE_SHIFT_ADJUST- Phase-shifter MW-flow angle adjustment. on (default) / off.--swshunt-adjustSWSHUNT_ADJUST- Switched-shunt discrete stepping. on (default) / off.--area-interchangeAREA_INTERCHANGE- Area-interchange control. off (default) / tie / tie-load.--low-voltage-loadPU- Voltage (pu) below which constant-power load tapers toward zero to bound low-voltage current. 0 (default) disables the taper. (default:0.0)-v,--verbose- Print run progress to stderr: setup-stage markers (parse, build, finalize) and a per-outer-pass solver trace. Auto-enabled for large inputs; silenced by -q.--minimal-nr- Minimal Newton-Raphson: no outer-loop, no FACTS/HVDC (debug mode)--no-remote- No remote voltage regulation from generators--no-facts-dc- No FACTS devices or VSC-HVDC--full- Show all tables (bus, gen, branch) regardless of system size--summary- Show summary only (no per-bus/branch tables)
The ``gpf`` command solves cases and runs power-system workflows. The main command solves RAW, RAWX, MATPOWER, OpenDSS, and mixed-system TOML inputs. It writes the result in text, HTML, or JSON format. Subcommands provide studies, case checks and edits, history, review, and agent access. Examples: gpf ieee14.rawx # Solve and print (auto-detect format) gpf case9.m # Solve MATPOWER case gpf IEEE13Nodeckt.dss # Solve an OpenDSS phase case gpf interconnection.toml # Solve a mixed-system manifest gpf ieee14.rawx -o # Save to ieee14.txt gpf ieee14.rawx -o result.html # Save as HTML (auto-detect from ext) gpf ieee14.rawx -o result.json # Save as JSON (auto-detect from ext) gpf ieee14.rawx --plain # Force plain text (no colors) gpf ieee14.rawx --json # Force JSON to stdout gpf large_case.raw --full # Show all tables for large systems gpf ieee14.rawx --summary # Show summary only (no tables) Terminal output detail: Automatic mode hides tables for large systems to keep output readable: <=200 buses: full output (bus + gen + branch tables) 201-500 buses: bus + gen tables (no branch) >500 buses: summary only (no tables) Use --full to show all tables. Use --summary to show only the summary. subcommands: gpf solve solve a power-flow case gpf doctor check case health and investigate convergence gpf diff compare two case files gpf explain summarize the effect of changes between two cases gpf apply apply a JSON patch to a case gpf scale scale, redispatch, or curtail a case gpf apply-topology apply node-breaker switch states to the bus-branch model gpf merge combine overlay cases with a base case gpf history show or verify a case's recorded history gpf checkout restore a recorded case version gpf export package a project and its resources as a portable bundle gpf import restore and verify a project snapshot gpf exhibit write recorded work to a portable HTML file gpf script-export write a recorded session as a Python script gpf study run scenario, contingency, and interconnection studies gpf fault run classical or IEC 60909 short-circuit studies gpf serve start the local review workbench gpf mcp start the MCP server for an AI assistant gpf license manage a licensed installation
Scenario studies: gpf study#
gpf study runs AC studies from a TOML study file or directly from a case.
Select a subcommand for the result that you need.
runRuns the scenarios and contingencies in a study file.
n-1Creates and runs a single-outage screen from a case. It checks every finalized AC branch against exact rating slot 1 and checks emergency voltage limits by default.
correctProposes control changes for overloads and verifies each change with an AC power flow.
scopfFinds the least-cost base dispatch that stays within limits for every contingency. It reports locational marginal prices. Options add corrective redispatch, losses, voltage-security remedies, and distributed slack.
atcCalculates the available transfer capability between
--fromand--tobuses. It ranks the limiting branches for the base case and for every outage the study file declares.--gen-limitedalso applies the available source generation. The linear model starts from the AC base-case flows;--base-flows dckeeps the lossless DC flows.screenScreens each declared generation or load request alone and with the declared queue. The binding table reports each request's deliverable output, what limits it, and the first network constraint. The screen table reports one row per calculation with its own flow evidence. The upgrades table estimates the rating each constraint needs for the full request.
headroomRanks the additional injection available at buses, line taps, or declared project plants. Use
--poi, an area and voltage scope, or--tap FROM-TO[-CKT][@PCT]. A[candidates]block can store the same selections in the study file.groupCalculates how much a group of network-resource projects can deliver together. The result accounts for the transfer share of every member.
screen, headroom, and group can evaluate one case or a seasonal
[[case]] set. They report the binding system condition for each candidate.
strengthReports three-phase short-circuit MVA, fault current, and short-circuit ratio for a weak-grid review.
pvandqvCalculate voltage-stability and reactive-power margins.
deltaRuns a study with and without its addition blocks and reports their effect.
schemaLists the valid fields for a study-file block.
importConverts
.con,.sub, and.monfiles to a gpf study file.validateChecks and resolves a study definition without solving it.
N-1 ratings and exit status#
The n-1 command separates the outage scope from the monitor scope. Area and
voltage filters select outages. The default thermal monitor still checks every
finalized AC branch because an outage can move flow outside the selected area.
--base-rating-set and --contingency-rating-set select exact slots. The
command does not substitute another slot when the selected rating is zero.
--loading-basis case reads XFRRAT and NXFRRAT. Use mva or current for an
explicit override. --missing-rating incomplete records missing PSS/E ratings
in coverage. --missing-rating error refuses the run. MATPOWER zero ratings
mean unlimited.
The report verdict is pass, fail, or incomplete. Status 0 means pass.
Status 1 means fail or incomplete. --convergence-only is the explicit
option that disables voltage and thermal criteria. See
Transmission contingency analysis for the full policy.
gpf study - CLI interface#
Run AC scenario and contingency studies.
gpf study [-h]
{run,n-1,correct,scopf,atc,screen,headroom,group,strength,pv,qv,delta,import,schema,validate}
...
gpf study options#
gpf study run#
run a study TOML file
gpf study run [-h] [--case CASE] [--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json]
[--csv FILE.csv] [--all] [--include-voltages]
study
gpf study run positional arguments#
study- study definition (.toml)
gpf study run options#
--caseCASE- override the study's base case path--backendBACKEND--outFILE.MD- write Markdown report--jsonFILE.JSON- write full JSON result--csvFILE.CSV- write ranked CSV table--all- keep every contingency in JSON (default: only failed/violating)--include-voltages- attach raw per-bus vm/va state to the JSON report
gpf study n-1#
generate and run an N-1 study from a case
gpf study n-1 [-h] [--area AREA] [--kv-min KV_MIN] [--kv-max KV_MAX] [--gens] [--name NAME]
[--save FILE.toml] [--retain {summary,file}] [--backend {cpu,cuda}]
[--out FILE.md] [--json FILE.json] [--csv FILE.csv] [--all]
[--include-voltages] [--voltage-band LO HI] [--base-rating-set N]
[--contingency-rating-set N] [--loading-basis {case,mva,current}]
[--missing-rating {incomplete,error}] [--thermal-threshold PCT]
[--convergence-only]
case
gpf study n-1 positional arguments#
case- base case (RAW/RAWX/MATPOWER)
gpf study n-1 options#
--areaAREA- restrict to area (repeatable)--kv-minKV_MIN- minimum base kV in scope--kv-maxKV_MAX- maximum base kV in scope--gens- also generate single-generator outages--nameNAME- study name--saveFILE.TOML- also save the generated study definition--retainRETAIN- result detail to preserve: summary (compact; a detailed read can require another calculation) or file (preserve voltage results between sessions) (default:summary)--backendBACKEND--outFILE.MD- write Markdown report--jsonFILE.JSON- write full JSON result--csvFILE.CSV- write ranked CSV table--all- keep every contingency in JSON (default: only failed/violating)--include-voltages- attach raw per-bus vm/va state to the JSON report--voltage-bandLO HI- monitor bus voltage against the [LO, HI] pu band--base-rating-setN- exact base rating slot 1..12 (default 1)--contingency-rating-setN- exact contingency rating slot 1..12 (default 1)--loading-basisLOADING_BASIS- thermal loading basis (default case)--missing-ratingMISSING_RATING- missing selected-rating policy (default incomplete)--thermal-thresholdPCT- flag branch loading above PCT percent of rating (default 100)--convergence-only- disable voltage and thermal release criteria
gpf study correct#
propose+verify corrective actions (generation MW, phase-shifter angle) that clear thermal overloads
gpf study correct [-h] [--case CASE] [--backend {cpu,cuda}] [--out FILE.md]
[--json FILE.json] [--max-rounds N] [--margin PCT]
[--max-shed-fraction FRAC]
study
gpf study correct positional arguments#
study- study definition (.toml)
gpf study correct options#
--caseCASE- override the study's base case path--backendBACKEND--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report--max-roundsN- propose/verify/re-size rounds per contingency (default 3)--marginPCT- oversize each shift by PCT percent (default 2)--max-shed-fractionFRAC- cap load curtailment at FRAC of each load's demand (0..1; default 1.0 = uncapped, emergency-capable)
gpf study scopf#
security-constrained OPF: least-cost base dispatch that stays within limits under every contingency (with LMP)
gpf study scopf [-h] [--case CASE] [--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json]
[--rating {normal,emergency}] [--eval-limit N] [--max-outer N] [--corrective]
[--ramp-window MIN] [--ramp-headroom FRAC] [--no-ac-verify] [--losses]
[--voltage-security] [--voltage-band LO HI] [--slack SPEC]
study
gpf study scopf positional arguments#
study- study definition (.toml) or a bare case file (auto N-1 over all single outages)
gpf study scopf options#
--caseCASE- override the study's base case path--backendBACKEND--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report--ratingRATING- exact post-contingency rating tier (default normal)--eval-limitN- evaluate at most N contingencies (default: all)--max-outerN- allow at most N AC security review passes (default: 4) (default:4)--corrective- corrective SCOPF: allow ramp-bounded post-contingency redispatch (cheaper than preventive; reports per-contingency remedial actions)--ramp-windowMIN- corrective ramp window in minutes (default 30)--ramp-headroomFRAC- use this fraction of available generator headroom when ramp data is absent (0..1; default: 1.0) (default:1.0)--no-ac-verify- stop at the DC-secure dispatch (skip AC verify)--losses- model DC losses and add a marginal-loss LMP component (energy + congestion + security + loss)--voltage-security- corrective voltage security: check post-contingency bus voltages and clear band violations with reactive controls (taps, shunts, setpoints); needs AC verify--voltage-bandLO HI- emergency voltage band pu (default: tightest emergency band across in-service buses)--slackSPEC- distributed slack participation: a bus number (single slack),'bus:weight,bus:weight'(grouped), or'areas'(per-area, needs --no-ac-verify). Moves the energy/congestion LMP split only; the dispatch and total price are unchanged.
gpf study atc#
available transfer capability of a source->sink transfer under the requested operating conditions
gpf study atc [-h] [--case CASE] --from BUS --to BUS [--rating {normal,emergency}] [--trm MW]
[--cbm MW] [--gen-limited] [--ac] [--ac-screen {full,candidates}]
[--backend {cpu,cuda}] [--base-flows {ac,dc}] [--slack SPEC] [--max-limiters K]
[--out FILE.md] [--json FILE.json]
study
gpf study atc positional arguments#
study- study definition (.toml) or a bare case file
gpf study atc options#
--caseCASE- override the study's base case path--fromBUS- source bus number (hub/zone endpoints are Python-API only)--toBUS- sink bus number--ratingRATING- exact post-contingency rating tier (default normal)--trmMW- transmission reliability margin (default 0)--cbmMW- capacity benefit margin (default 0)--gen-limited- also cap the transfer at the source's generation headroom (sum of Pmax - Pg at the source bus)--ac- verify the reported transfer with an AC study--ac-screenAC_SCREEN- AC verification scope (requires --ac): full checks all evaluated contingencies; candidates checks only the highest-ranked DC limiters (default: full)--backendBACKEND- AC solve backend for --ac--base-flowsBASE_FLOWS- DC tier zero-transfer flows: ac starts from the AC base-case solution (default); dc keeps the lossless DC flows--slackSPEC- DC-tier slack participation:'areas', a bus number, or'bus:weight,bus:weight'(who picks up a tripped generator's MW; the balanced transfer itself is participation-invariant)--max-limitersK- ranked limiter table depth (default 25)--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study screen#
report deliverability for declared projects
gpf study screen [-h] [--case FILE] [--to BUS] [--rating {normal,emergency}] [--ac]
[--backend {cpu,cuda}] [--max-limiters K] [--strength] [--out FILE.md]
[--json FILE.json]
study
gpf study screen positional arguments#
study- study definition (.toml) with [[project]]/[[load]] blocks
gpf study screen options#
--caseFILE- override the study's base case path; repeat for a seasonal case set (the binding case per project is reported). Per-case dispatch assumptions need [[case]] blocks in the study--toBUS- transfer counterparty bus instead of system displacement; withdrawal for generation projects, source for load projects--ratingRATING- exact post-contingency rating tier (default normal)--ac- add an AC-verified deliverable column (the with-queue variant, voltage/stability limit types included)--backendBACKEND- AC solve backend for --ac--max-limitersK- limiter table depth per ATC run (default 25)--strength- add SCMVA/SCR columns (system strength at the POI on the base network; weak grid = EMT-study risk)--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study headroom#
report injection headroom for candidate locations
gpf study headroom [-h] [--case FILE] [--poi BUS] [--tap FROM-TO[-CKT][@PCT]] [--area A]
[--kv-min KV] [--kv-max KV] [--sink-bus BUS] [--rating {normal,emergency}]
[--trm MW] [--cbm MW] [--ac] [--verify-top K] [--backend {cpu,cuda}]
[--max-limiters K] [--strength] [--out FILE.md] [--json FILE.json]
study
gpf study headroom positional arguments#
study- study definition (.toml); with [[project]] blocks and no --poi it runs project mode
gpf study headroom options#
--caseFILE- override the study's base case path; repeat for a seasonal case set (the binding case per POI is reported). Per-case dispatch assumptions need [[case]] blocks in the study--poiBUS- candidate POI bus (repeatable); screen mode--tapFROM-TO[-CKT][@PCT]- candidate POI on a line TAP between two buses (repeatable): the branch is split at PCT percent from FROM (default 50) and the new tap bus is the POI, ranked beside the --poi buses--areaA- resolve candidate POIs from an area (repeatable)--kv-minKV- lower kV bound for scope-resolved candidate POIs--kv-maxKV- upper kV bound for scope-resolved candidate POIs--sink-busBUS- withdraw at a single bus instead of the default system displacement (pro-rata to generation); settlement-point sinks are Python-API only--ratingRATING- exact post-contingency rating tier (default normal)--trmMW- transmission reliability margin (default 0)--cbmMW- capacity benefit margin (default 0)--ac- AC-verify the ranked head (screen mode) or every project (project mode)--verify-topK- AC-verify the top K POIs by DC headroom (screen mode, default 5)--backendBACKEND- AC solve backend for --ac--max-limitersK- limiter table depth per POI (default 25)--strength- add SCMVA/SCR columns (system strength at the POI on the base network; weak grid = EMT-study risk)--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study group#
simultaneous group deliverability: how many MW the [[project]] blocks declaring the network-resource service can put on the network TOGETHER, split per member (not recoverable from the per-project screens)
gpf study group [-h] [--case FILE] [--sink-bus BUS] [--rating {normal,emergency}] [--trm MW]
[--cbm MW] [--ac] [--backend {cpu,cuda}] [--max-limiters K] [--out FILE.md]
[--json FILE.json]
study
gpf study group positional arguments#
study- study definition (.toml) with [[project]] blocks declaring the network-resource service
gpf study group options#
--caseFILE- override the study's base case path; repeat for a seasonal case set (the binding case per member is reported). Per-case dispatch assumptions need [[case]] blocks in the study--sink-busBUS- withdraw at a single bus instead of the default system displacement (pro-rata to generation); settlement-point sinks are Python-API only--ratingRATING- exact post-contingency rating tier (default normal)--trmMW- transmission reliability margin (default 0)--cbmMW- capacity benefit margin (default 0)--ac- AC-verify the group transfer and make it the ranked tier--backendBACKEND- AC solve backend for --ac--max-limitersK- limiter table depth for the group transfer (default 25)--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study strength#
system strength: three-phase short-circuit MVA, fault kA, and SCR at buses (the interconnection screen's short-circuit number)
gpf study strength [-h] [--case CASE] [--bus BUS] [--mw MW] [--scr-threshold X]
[--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json]
study
gpf study strength positional arguments#
study- study definition (.toml) or a bare case file
gpf study strength options#
--caseCASE- override the study's base case path--busBUS- bus to screen (repeatable; default: every bus)--mwMW- project MW to ratio against: adds SCR and the weak-grid flag--scr-thresholdX- SCR below this flags weak grid (default 3.0)--backendBACKEND- backend for the network build--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study pv#
PV curve: trace the voltage-stability margin of a load growth and report its maximum
gpf study pv [-h] [--case CASE] --sink BUS [--source BUS] [--stop-mw STOP_MW]
[--limit-mode {enforce,hold}] [--maximum-mode {pin,estimate}]
[--initial-step INITIAL_STEP] [--minimum-voltage-pu PU|off]
[--point-limit POINT_LIMIT] [--corrector-tolerance CORRECTOR_TOLERANCE]
[--solve-max-iter SOLVE_MAX_ITER] [--solve-tol SOLVE_TOL]
[--solve-q-tol SOLVE_Q_TOL] [--solve-var-limit-start {off,immediate,automatic}]
[--solve-ac-tap-adjust {enabled,disabled}]
[--solve-lcc-dc-tap-adjust {enabled,disabled}]
[--solve-phase-shift-adjust {enabled,disabled}]
[--solve-swshunt-adjust {enabled,disabled}]
[--solve-low-voltage-load-pu SOLVE_LOW_VOLTAGE_LOAD_PU] [--backend {cpu,cuda}]
[--out FILE.md] [--json FILE.json]
study
gpf study pv positional arguments#
study- study definition (.toml) or a bare case file
gpf study pv options#
--caseCASE- override the study's base case path--sinkBUS- load-growth bus (repeatable; growth at base power factor)--sourceBUS- sourcing bus (repeatable; default: slack absorbs)--stop-mwSTOP_MW- stop after this additional transfer (MW)--limit-modeLIMIT_MODE- Select whether the trace reapplies finite reactive-power and current limits as loading changes or holds the base solution's voltage-control regime fixed.--maximum-modeMAXIMUM_MODE- Select how the study reports a maximum after the trace detects one. Pinning cannot locate a maximum when a stop condition ends the trace before detection.--initial-stepINITIAL_STEP- Set the positive initial step in normalized curve state. Reduce it when the first curve points do not converge.--minimum-voltage-puPU|OFF- Stop when the minimum PQ-bus voltage falls below this per-unit value. This is a stop condition, not a guaranteed loading margin. Leave empty to disable this stop.--point-limitPOINT_LIMIT- Stop after this many accepted curve points, including the starting point. Reaching the limit can end the trace before it crosses a maximum.--corrector-toleranceCORRECTOR_TOLERANCE- Accept a curve point when its maximum per-unit residual is below this positive tolerance.--solve-max-iterSOLVE_MAX_ITER- Maximum number of Newton iterations allowed for the solve.--solve-tolSOLVE_TOL- The solve converges when its maximum equation residual is below this per-unit tolerance.--solve-q-tolSOLVE_Q_TOL- Reactive-power slack, in per unit, used when the voltage-regulation enforcer applies or releases device limits.--solve-var-limit-startSOLVE_VAR_LIMIT_START- Select when the solver enforces reactive-power and current limits for voltage-regulating devices.--solve-ac-tap-adjustSOLVE_AC_TAP_ADJUST- Controls tap-ratio adjustment by voltage-controlling AC transformers.--solve-lcc-dc-tap-adjustSOLVE_LCC_DC_TAP_ADJUST- Controls rectifier and inverter tap-ratio adjustment for LCC HVDC links.--solve-phase-shift-adjustSOLVE_PHASE_SHIFT_ADJUST- Controls angle adjustment by phase-shifting transformers in active-power-flow control mode.--solve-swshunt-adjustSOLVE_SWSHUNT_ADJUST- Controls susceptance adjustment by discrete and continuous switched shunts.--solve-low-voltage-load-puSOLVE_LOW_VOLTAGE_LOAD_PU- Voltage threshold, in per unit, below which constant-power load is smoothly tapered toward zero to bound current at low voltage. Zero disables the taper.--backendBACKEND- backend for the trace--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report
gpf study qv#
QV curve: trace the reactive margin at a bus (pure-Q load growth)
gpf study qv [-h] [--case CASE] --bus BUS [--stop-mvar STOP_MVAR]
[--limit-mode {enforce,hold}] [--maximum-mode {pin,estimate}]
[--initial-step INITIAL_STEP] [--minimum-voltage-pu PU|off]
[--point-limit POINT_LIMIT] [--corrector-tolerance CORRECTOR_TOLERANCE]
[--solve-max-iter SOLVE_MAX_ITER] [--solve-tol SOLVE_TOL]
[--solve-q-tol SOLVE_Q_TOL] [--solve-var-limit-start {off,immediate,automatic}]
[--solve-ac-tap-adjust {enabled,disabled}]
[--solve-lcc-dc-tap-adjust {enabled,disabled}]
[--solve-phase-shift-adjust {enabled,disabled}]
[--solve-swshunt-adjust {enabled,disabled}]
[--solve-low-voltage-load-pu SOLVE_LOW_VOLTAGE_LOAD_PU] [--backend {cpu,cuda}]
[--out FILE.md] [--json FILE.json]
study
gpf study qv positional arguments#
study- study definition (.toml) or a bare case file
gpf study qv options#
--caseCASE- override the study's base case path--busBUS- study bus (repeatable; one curve each)--stop-mvarSTOP_MVAR- stop after this reactive withdrawal (Mvar)--limit-modeLIMIT_MODE- Select whether the trace reapplies finite reactive-power and current limits as loading changes or holds the base solution's voltage-control regime fixed.--maximum-modeMAXIMUM_MODE- Select how the study reports a maximum after the trace detects one. Pinning cannot locate a maximum when a stop condition ends the trace before detection.--initial-stepINITIAL_STEP- Set the positive initial step in normalized curve state. Reduce it when the first curve points do not converge.--minimum-voltage-puPU|OFF- Stop when the minimum PQ-bus voltage falls below this per-unit value. This is a stop condition, not a guaranteed loading margin. Leave empty to disable this stop.--point-limitPOINT_LIMIT- Stop after this many accepted curve points, including the starting point. Reaching the limit can end the trace before it crosses a maximum.--corrector-toleranceCORRECTOR_TOLERANCE- Accept a curve point when its maximum per-unit residual is below this positive tolerance.--solve-max-iterSOLVE_MAX_ITER- Maximum number of Newton iterations allowed for the solve.--solve-tolSOLVE_TOL- The solve converges when its maximum equation residual is below this per-unit tolerance.--solve-q-tolSOLVE_Q_TOL- Reactive-power slack, in per unit, used when the voltage-regulation enforcer applies or releases device limits.--solve-var-limit-startSOLVE_VAR_LIMIT_START- Select when the solver enforces reactive-power and current limits for voltage-regulating devices.--solve-ac-tap-adjustSOLVE_AC_TAP_ADJUST- Controls tap-ratio adjustment by voltage-controlling AC transformers.--solve-lcc-dc-tap-adjustSOLVE_LCC_DC_TAP_ADJUST- Controls rectifier and inverter tap-ratio adjustment for LCC HVDC links.--solve-phase-shift-adjustSOLVE_PHASE_SHIFT_ADJUST- Controls angle adjustment by phase-shifting transformers in active-power-flow control mode.--solve-swshunt-adjustSOLVE_SWSHUNT_ADJUST- Controls susceptance adjustment by discrete and continuous switched shunts.--solve-low-voltage-load-puSOLVE_LOW_VOLTAGE_LOAD_PU- Voltage threshold, in per unit, below which constant-power load is smoothly tapered toward zero to bound current at low voltage. Zero disables the taper.--backendBACKEND- backend for the trace--outFILE.MD- write Markdown report--jsonFILE.JSON- write JSON report (a list when --bus repeats)
gpf study delta#
run a study without and with its [[addition]]/[[project]] blocks and attribute the difference (which violations the additions caused)
gpf study delta [-h] [--case CASE] [--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json]
study
gpf study delta positional arguments#
study- study definition (.toml) with additions
gpf study delta options#
gpf study import#
import a .con/.sub/.mon trio to a study TOML
gpf study import [-h] [--sub SUB] [--mon MON] [--base BASE] -o FILE.toml con
gpf study import positional arguments#
con- contingency file (.con)
gpf study import options#
gpf study schema#
field spec of any study TOML block (case, project, load, sweep, candidates, monitor, interface, contingency, cost, group, addition, dispatch)
gpf study schema [-h] [--json]
{case,project,load,sweep,candidates,monitor,interface,contingency,cost,group,addition,dispatch}
gpf study schema positional arguments#
block- which block to describe
gpf study schema options#
gpf study validate#
resolve a study against its case without solving
gpf study validate [-h] [--case CASE] [--backend {cpu,cuda}] study
gpf study validate positional arguments#
study- study definition (.toml)
gpf study validate options#
An example study file#
The study file below contains every block an interconnection request needs: a seasonal case set with its per-fuel dispatch assumptions, two generation projects entered in the simultaneous-delivery study and one entered on its own, a large-load request, candidate points of interconnection including a line tap, a monitored subsystem, and an explicit contingency. The Interconnection studies tutorial in the gpf User Guide explains the resulting screens.
# An interconnection queue study, with every block a request needs.
#
# The network is a five-bus system at 230 kV. Buses 1, 2 and 3 form a triangle
# in which 1-2 is rated 200 MVA and the other two legs 300 MVA, so 1-2 is the
# corridor that binds; buses 4 and 5 hang off bus 1 on well-rated lines. Bus 1
# carries the only existing machine and is the reference.
#
# Four requests are declared against it: two generation projects entered in the
# simultaneous-delivery study, one entered on its own, and one large load.
[study]
name = "Interconnection queue screen"
format = 5
[study.options]
tol = 1e-8
max_iter = 40
# --- The case set -------------------------------------------------------------
#
# A request is screened in several system conditions and reported at the binding
# one. Each block names its own case file and the fraction of declared output a
# project of each fuel kind is assumed to run at there. A "kind/service" key
# overrides the bare "kind" for projects declaring that service, so two projects
# of the same fuel asking for different interconnection service are stressed
# differently. A missing key is 1.0.
[[case]]
name = "summer_peak"
file = "summer_peak.raw"
dispatch = { solar = 1.0, wind = 0.35, load = 1.0, "wind/network" = 0.40 }
[[case]]
name = "winter_peak"
file = "winter_peak.raw"
dispatch = { solar = 0.4, wind = 0.80, load = 1.0, "wind/network" = 0.45 }
[[case]]
name = "light_load"
file = "light_load.raw"
dispatch = { solar = 0.9, wind = 0.70, load = 0.4, "wind/network" = 0.80 }
# --- The queue ----------------------------------------------------------------
#
# A [[project]] block is one interconnection request. Its resources are the
# technology-specific machine equivalents. Naming plant_bus, plant_kv and a
# gsu sub-table sites every resource behind one step-up transformer.
#
# "service" is what the project asked for, and it is what decides which study
# answers it. A network-resource declaration is a claim about what a set of
# resources delivers at the same time, so those projects are answered together
# as one simultaneous transfer; every other declaration is answered one project
# at a time.
[[project]]
label = "P1"
poi_bus = 2
request_mw = 300.0
resources = [{ technology = "wind", mw = 300.0, power_factor = 0.95 }]
service = "network"
plant_bus = 90001
plant_kv = 34.5
gsu = { mva = 330.0, x_pct = 7.5 }
[[project]]
label = "P2"
poi_bus = 3
request_mw = 200.0
resources = [{ technology = "wind", mw = 200.0, power_factor = 0.95 }]
service = "network"
plant_bus = 90002
plant_kv = 34.5
gsu = { mva = 220.0, x_pct = 7.5 }
# Energy service: screened on its own, not as a member of the group.
[[project]]
label = "P3"
poi_bus = 4
request_mw = 120.0
resources = [
{ technology = "solar", mw = 90.0, id = "S1", power_factor = 0.95 },
{ technology = "storage", mw = 50.0, id = "B1", power_factor = 0.95, pmin = -50.0, dispatch_mw = 30.0 },
]
service = "energy"
# A large-load request is the same declaration in the withdrawal direction.
# served_mw = 0 places the load in the case unserved, which is the screening
# pose: the question is how much demand the point absorbs before a limit binds.
# The id distinguishes it from the load already at that bus.
[[load]]
label = "L1"
poi_bus = 5
id = "2"
mw = 90.0
power_factor = 0.98
served_mw = 0.0
service = "energy"
# --- Candidates, monitoring, contingencies ------------------------------------
#
# A scope is a bus filter written where it is used: a device is in it when it
# is wired to a bus the filter selects.
# The points of interconnection a bus screen answers for, independent of the
# declared queue. The three lists are additive: named buses, line taps, and
# every bus a named scope selects. A tap is a candidate point BETWEEN two
# buses; the named line is split at pct percent from its "from" end and the new
# bus is the point of interconnection.
[candidates]
buses = [3, 4]
taps = [ { from = 4, to = 5, ckt = "1", pct = 40.0 } ]
# Voltages are checked on every bus the subsystem selects. Thermal loading is
# checked on every branch in the subsystem against exact slot 1 at 100 percent.
[monitor]
voltage = { scope = { areas = [1, 2], kv_min = 100.0, kv_max = 999.0 }, voltage_band = [0.95, 1.05] }
thermal = { scope = { areas = [1, 2], kv_min = 100.0, kv_max = 999.0 }, base_rating_set = 1, contingency_rating_set = 1 }
# A sweep takes out every device of one family in turn, inside a scope when one
# is given. A named contingency lists the branches and machines it takes out
# together; more than one is an N-2 or N-k.
[[sweep]]
family = "branch"
[[contingency]]
label = "loss of 1-3"
branches = [ { from = 1, to = 3, ckt = "1" } ]
Short circuit: gpf fault#
gpf fault runs classical and IEC 60909 short-circuit studies. Use --seq to
supply the required sequence data.
runFaults one bus, a selected set of buses, or every bus. The report includes sequence and phase currents, Thevenin impedance, X/R, and IEC duty values.
--contribadds equipment contributions. The prefault profile can beflat,uniform, orsolved.deltaCompares fault current at monitored buses in two cases. Exit status
0means that no change exceeds the threshold,1means that a change exceeds it, and2means that an error occurred.
gpf fault - CLI interface#
Run a classical or IEC 60909 short-circuit study for one bus, selected buses, all buses, or a case comparison.
gpf fault [-h] {run,delta} ...
gpf fault options#
gpf fault run#
Run faults at selected buses or at every bus.
gpf fault run [-h] --seq FILE.seq [--iec FILE.iec] [--bus BUS] [--zf R,X] [--zg R,X]
[--scale SCALE] [--tmin TMIN] [--tk TK]
[--solved-sources {characteristic,dispatch}] [--no-zcorec] [--contrib CONTRIB]
[--contrib-all] [--kind {3ph,slg,ll,llg}] [--method {classical,iec}]
[--prefault {flat,uniform,solved}]
[--tier {subtransient,transient,synchronous}] [--variant {cmax,cmin}]
[--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json] [--csv FILE.csv]
case
gpf fault run positional arguments#
case- Case file (.raw, .rawx, .m).
gpf fault run options#
--seqFILE.SEQ- Sequence-data file (required).--iecFILE.IEC- IEC 60909 machine-data file (optional).--busBUS- Fault this bus; repeat for several. Omit to sweep every bus.--zfR,X- Fault impedance pu (default 0 = bolted).--zgR,X- Ground-path impedance pu for L-L-G (default 0).--scaleSCALE- Prefault voltage scale (default 1.0).--tminTMIN- IEC breaker minimum time delay s (default 0.1).--tkTK- IEC thermal-equivalent duration s (default 1.0).--solved-sourcesSOLVED_SOURCES- Converter-source model under a solved prefault. (default:characteristic)--no-zcorec- Disable the zero-sequence transformer impedance correction.--contribCONTRIB- Emit contribution + voltage detail at this bus; repeat for several.--contrib-all- Emit contribution detail at every faulted bus.--kindKIND- Fault type(s); repeat for several (default 3ph).--methodMETHOD- Fault method (default classical; iec = IEC 60909 duty).--prefaultPREFAULT- Classical prefault profile (default flat = EMF-flat; uniform = every bus at scale angle 0; solved = operating point).--tierTIER- Machine reactance tier (default subtransient).--variantVARIANT- IEC voltage-factor variant (default cmax).--backendBACKEND--outFILE.MD- Write the Markdown report.--jsonFILE.JSON- Write the JSON report.--csvFILE.CSV- Write the fault table as CSV.
gpf fault delta#
Fault-current change between two cases.
gpf fault delta [-h] [--seq FILE.seq] [--seq-a FILE.seq] [--seq-b FILE.seq] [--iec FILE.iec]
[--iec-a FILE.iec] [--iec-b FILE.iec] [--bus BUS] [--threshold PCT]
[--kind {3ph,slg,ll,llg}] [--method {classical,iec}]
[--prefault {flat,uniform,solved}]
[--tier {subtransient,transient,synchronous}] [--variant {cmax,cmin}]
[--backend {cpu,cuda}] [--out FILE.md] [--json FILE.json] [--csv FILE.csv]
base current
gpf fault delta positional arguments#
gpf fault delta options#
--seqFILE.SEQ- Sequence-data file for both cases.--seq-aFILE.SEQ- Sequence-data file for the baseline (overrides --seq).--seq-bFILE.SEQ- Sequence-data file for the current case (overrides --seq).--iecFILE.IEC- IEC 60909 machine-data file for both cases.--iec-aFILE.IEC--iec-bFILE.IEC--busBUS- Monitor this bus; repeat for several. Omit for all.--thresholdPCT- Flag rows whose change magnitude reaches this percent (default 0 = any change).--kindKIND- Fault type(s); repeat for several (default 3ph).--methodMETHOD- Fault method (default classical; iec = IEC 60909 duty).--prefaultPREFAULT- Classical prefault profile (default flat = EMF-flat; uniform = every bus at scale angle 0; solved = operating point).--tierTIER- Machine reactance tier (default subtransient).--variantVARIANT- IEC voltage-factor variant (default cmax).--backendBACKEND--outFILE.MD- Write the Markdown report.--jsonFILE.JSON- Write the JSON report.--csvFILE.CSV- Write the fault table as CSV.
Case health: gpf doctor#
gpf doctor checks a case, reports conditions that need review, and can apply
available repairs. Run a read-only check with:
gpf doctor CASE
Use --fix with --output to write the available repairs. The command
shows each proposed change. The Case doctor reference lists the
finding codes and available repairs.
gpf doctor - CLI interface#
Case health report and convergence troubleshooting
gpf doctor [-h] [--areas AREAS] [--level {static,deep,full}] [--probes PROBES]
[--profile PROFILE] [--timeout TIMEOUT] [--no-early-stop] [--backend {cpu,cuda}]
[--var-limit MODE] [--tap-adjust {on,off}] [--lcc-dc-tap-adjust {on,off}]
[--phase-shift-adjust {on,off}] [--swshunt-adjust {on,off}]
[--area-interchange {off,tie,tie-load}] [--max-iter MAX_ITER] [--tol TOL]
[--rebalance] [--markdown MARKDOWN] [--json JSON_OUT] [--artifacts ARTIFACTS]
[--output-mismatch OUTPUT_MISMATCH] [--allow {physical-equipment,topology}]
[--fix] [-o OUTPUT] [--write-as {30,33,34,35,36}] [--no-track] [--fail-on FAIL_ON]
[-q]
input
gpf doctor positional arguments#
input- Input case (.raw, .rawx, .m)
gpf doctor options#
--areasAREAS- Comma-separated area codes to extract before examining--levelLEVEL- Check depth (default: %(default)s).'static'checks data and model support;'deep'adds checks that need a backend;'full'adds solve and convergence checks. (default:static)--probesPROBES- Comma-separated advanced check selectors. This option overrides --level. Use selectors supplied by support.--profilePROFILE- Conformance profile name or profile file. The report includes a pass or fail table and exits 1 when a required check fails.--timeoutTIMEOUT- Maximum run time in seconds (default: 300). Zero removes the limit. (default:300.0)--no-early-stop- Run every selected check after the doctor has enough evidence for a verdict.--backendBACKEND- Solver backend (default: auto-detect, prefer CPU)--var-limitMODE- VAR-limit policy:'off'(never enforce),'immediate'(enforce from the first control review), or'automatic'(enforce after the case first converges). Default: file-format aware — .raw/.rawx/.json use'immediate', .m uses'off'(MATPOWER's enforce_q_lims=0).--tap-adjustTAP_ADJUST- AC tap-changer stepping. on (default) / off.--lcc-dc-tap-adjustLCC_DC_TAP_ADJUST- LCC HVDC TAPR/TAPI stepping. on (default) / off.--phase-shift-adjustPHASE_SHIFT_ADJUST- Phase-shifter MW-flow angle adjustment. on (default) / off.--swshunt-adjustSWSHUNT_ADJUST- Switched-shunt discrete stepping. on (default) / off.--area-interchangeAREA_INTERCHANGE- Area-interchange control. off (default) / tie / tie-load.--max-iterMAX_ITER- Maximum solve iterations used by full checks--tolTOL- Convergence tolerance in per unit for full checks--rebalance- Scale generation 1.02x load after area extraction--markdownMARKDOWN- Write markdown report to this file (else print to stdout)--jsonJSON_OUT- Write structured JSON report to this file--artifactsARTIFACTS- Directory for detailed support artifacts--output-mismatchOUTPUT_MISMATCH- Write top-N decoded mismatch CSV to this file--allowALLOW- Permit repairs in the selected higher-impact category (default:[])--fix- Apply safe data repairs and write the repaired case to --output. Topology changes need --allow topology. Never writes in place.-oOUTPUT,--outputOUTPUT- Output path for --fix (default: .doctored) --write-asWRITE_AS- RAW version for --fix output when the input version has no same-version writer; an explicit downgrade, declared lossy in the report--no-track- Do not record the repaired case in its history.--fail-onFAIL_ON- Comma-separated IssueCode names; exit 1 if any listed code fires (CI gate), e.g. NO_VIABLE_SLACK,ISOLATED_BUS
Case diff: gpf diff#
gpf diff compares two case files and reports added, removed, and changed
records. It identifies each record by its power-system identity, such as a bus
number, branch terminals and circuit ID, or generator bus and ID.
The default comparison is exact. Use --tol to ignore smaller numeric
differences. Exit status 0 means that the cases are identical, 1 means that
they differ, and 2 means that an error occurred. --json writes a patch that
gpf apply can use.
--solve compares the two operating points instead of their records. It
reports changes in bus voltages, generator outputs, and branch flows.
gpf diff - CLI interface#
Compare two case files and report added, removed, and changed records.
gpf diff [-h] [--tol TOL] [--family FAMILY] [--limit LIMIT] [--solve] [--json] a b
gpf diff positional arguments#
gpf diff options#
--tolTOL- Absolute tolerance for numeric fields (default 0.0 = exact).--familyFAMILY- Restrict output to these comma-separated families (e.g.'branches,generators'). Default: all.--limitLIMIT- Max changed records listed per family in text output (default 20).--solve- Solve both cases and diff the operating points (bus voltages, generator outputs, branch flows) instead of the model records.--json- Emit the machine-readable JSON diff instead of the text report.
Impact report: gpf explain#
gpf explain solves two cases and summarizes the material effect of their
differences. The report identifies the most important result and includes:
topology changes;
changes in load, generation, slack pickup, and area interchange;
the largest voltage changes and created or cleared voltage violations;
new or relieved branch overloads; and
changes in convergence, islands, and generator reactive limits.
--band applies one voltage band instead of the limits from the case.
--rating selects a branch rating set, --top limits each ranked list, and
--json writes the complete structured report. If a case does not converge,
the report identifies it and marks unavailable flow results. Exit status 0
means no material impact, 1 means an impact was found, and 2 means that an
error occurred.
gpf explain - CLI interface#
Explain what changed between two cases and what it did to the network (topology, dispatch, voltage, thermal, health).
gpf explain [-h] [--solve] [--no-solve] [--band LO HI] [--rating N] [--top K] [--json] a b
gpf explain positional arguments#
gpf explain options#
--solve- Solve both cases and populate the flow sections (default).--no-solve- Skip solving; report only the record-level (topology/load) delta.--bandLO HI- Global voltage band in pu (default: each bus's own nvlo/nvhi).--ratingN- Rating set 1..12 for branch loading (default 1 = Rating A).--topK- Max movers listed per section (default 10).--json- Emit the full JSON impact report instead of the headline.
Apply a patch: gpf apply#
gpf apply applies a JSON patch from gpf diff --json to a base case. The
command checks that the original value in each changed record still matches the
base case. A mismatch is a conflict. Use --on-conflict skip to omit conflicting
changes or --on-conflict force to apply them.
-o writes the patched case. Without -o, the command reports the proposed
changes and writes nothing. Exit status 0 means success. Exit status 2
means that an error or conflict occurred.
gpf apply - CLI interface#
Apply a JSON patch from `gpf diff --json` to a case.
gpf apply [-h] [-o OUT] [--on-conflict {raise,skip,force}] [--no-track] patch case
gpf apply positional arguments#
gpf apply options#
-oOUT,--outOUT- Write the patched case here (.raw / .rawx). Omit for a dry run that reports what would change and writes nothing.--on-conflictON_CONFLICT- When a changed record no longer matches the base case: raise (default), skip the change, or force it. (default:raise)--no-track- Do not record this write in the case history.
Parametric transform: gpf scale#
gpf scale scales loads, generators, or shunts, redispatches generation, or
curtails load. --op selects the operation. --params supplies its parameters
as JSON, for example {"areas":[2],"multiplier":1.1}.
-o writes the modified case. --patch writes the resulting changes as a
patch for review or later use with gpf apply. Without -o, the command
reports the proposed changes and writes nothing.
gpf scale - CLI interface#
Scale loads, generators, or shunts, redispatch generation, or curtail load.
gpf scale [-h] --op
{scale_loads,scale_generators,scale_shunts,dispatch_generators,curtail_loads}
[--params PARAMS] [-o OUT] [--patch PATCH] [--no-track]
case
gpf scale positional arguments#
case- Case to transform (.raw, .rawx, .m)
gpf scale options#
--opOP- Change to apply.--paramsPARAMS- Op parameters as a JSON object, e.g.'{"areas":[2],"multiplier":1.1}'or'{"machines":[[101,"1",1.0]],"delta_mw":50}'. (default:{})-oOUT,--outOUT- Write the transformed case here (.raw / .rawx). Omit for a dry run.--patchPATCH- Also write the resulting changes as a JSON patch forgpf apply.--no-track- Do not record this write in the case history.
Apply the node layer: gpf apply-topology#
gpf apply-topology applies node-breaker switch states to the bus-branch model.
An open switch can divide one bus into disconnected sections. A closed switch
can connect sections from two buses. The command:
creates buses for disconnected sections;
moves equipment according to its terminal node;
marks a disconnected section without a swing source as isolated; and
represents a cross-bus switch as an open or closed branch.
This operation resolves case-doctor finding 910. --version selects the output
RAW revision. If you omit it, the command uses the case revision and keeps the
node layer. Use revision 33 to write only the reconciled bus-branch model.
-o writes the reconciled case. Without -o, the command reports the proposed
changes and writes nothing.
gpf apply-topology - CLI interface#
Apply node-breaker switch states to a case's bus-branch model.
gpf apply-topology [-h] [-o OUT] [--version {30,33,34,35,36}] [--no-track] case
gpf apply-topology positional arguments#
case- Case to transform (.raw, .rawx)
gpf apply-topology options#
-oOUT,--outOUT- Write the reconciled case here (.raw / .rawx). Omit for a dry run.--versionVERSION- RAW revision to write. Omit this option to use the case revision and keep the node layer. Use revision 33 to omit the node layer.--no-track- Do not record this write in the case history.
Case merge: gpf merge#
gpf merge combines one or more overlay cases with a base case. It matches
records by their power-system identity. A record that appears in only one file
is included, and identical records merge without a conflict.
Different values for the same record cause a conflict. The default error
policy reports all conflicts and does not write a case. overlay_wins uses the
value from the last overlay, and base_wins keeps the first value. All input
files must use the same bus-numbering scheme.
-o writes the merged case. Without -o, the command reports the proposed
merge and writes nothing.
gpf merge - CLI interface#
Combine overlay case files with a base case. Different values for the same record are conflicts.
gpf merge [-h] [-o OUTPUT] [--on-conflict {error,overlay_wins,base_wins}] [--no-track]
base overlays [overlays ...]
gpf merge positional arguments#
gpf merge options#
-oOUTPUT,--outputOUTPUT- Write the merged case here (.raw, .rawx, .json). Default: report only.--on-conflictON_CONFLICT- Policy for different values on the same record (default: error). (default:error)--no-track- Do not record this write in the case history.
Version history: gpf history#
gpf history shows each recorded version of a case and the operation that
created it.
Changes made outside gpf appear in the history when the case is opened again.
The editing commands record a version by default. Use --no-track when a
write must not enter the history. --verify checks the stored history, and
--compact reduces its storage while preserving restorable versions. A case
without recorded history remains unchanged.
gpf history - CLI interface#
Show the recorded versions of a case and the operation that created each version.
gpf history [-h] [--verify] [--compact] case
gpf history positional arguments#
case- Case file (.raw, .rawx, .m)
gpf history options#
Reconstruct a version: gpf checkout#
gpf checkout restores a recorded version of a case. --at accepts a sequence
number or the identifier shown by gpf history. The latest version is the
default. -o writes the restored case. The command reports a problem when the
stored history cannot reproduce the requested version.
gpf checkout - CLI interface#
Restore a recorded version of a case.
gpf checkout [-h] [--at SEQ|HASH] [-o OUT] case
gpf checkout positional arguments#
case- Case file with recorded history
gpf checkout options#
Portable bundle: gpf export#
gpf export project.toml -o project.zip captures the project and its declared
resources, including coordinates, diagrams, studies, results, and available
history. It does not require recorded history or change the source project.
gpf export - CLI interface#
Package a project and its resources as a portable bundle.
gpf export [-h] -o BUNDLE.zip project
gpf export positional arguments#
project- Project manifest (.toml)
gpf export options#
Import a bundle: gpf import#
gpf import project.zip -o restored verifies the complete snapshot before
restoring it. It preserves project and resource identities and refuses conflicting
destination files. Legacy case/history archives migrate into projects during
import. History-only archives reconstruct their current network at that boundary.
gpf import - CLI interface#
Verify and restore a complete project snapshot in a directory.
gpf import [-h] -o DIR bundle
gpf import positional arguments#
bundle- Bundle zip written by gpf export
gpf import options#
Write an exhibit: gpf exhibit#
gpf exhibit writes recorded operations and case history to one self-contained
HTML file. The recipient does not need gpf to open it. The command verifies the
included records and reports any problem.
The default output omits large history data. Use --with-snapshots when the
recipient must verify the complete included history. Use --verify to check
the working directory without writing an exhibit.
gpf exhibit - CLI interface#
Write recorded operations and case histories under a directory to one self-contained HTML exhibit.
gpf exhibit [-h] (-o FILE.html | --verify) [--with-snapshots] [root]
gpf exhibit positional arguments#
root- Directory to search for recorded work (default: the current directory). (default:.)
gpf exhibit options#
--verify- Verify all recorded operations and case histories. Exit status 1 reports failed verification. This option writes nothing.--with-snapshots- Include the data required for independent history verification. This produces a much larger file.
Session as a script: gpf script-export#
gpf script-export writes a Python script that repeats the successful
operations from a recorded session. It omits failed operations, pending or
completed review decisions, and read-only operations. --include-reads also
includes read-only operations.
--list shows the available sessions, and --session selects one. Without
--session, the command selects the most recently active session.
--assert-hashes verifies the case after each modifying operation and stops
the script at the first different result.
The exported script contains the recorded case path. Update the load_case
line before you run the script on another machine. If one session used cases
from different directories, export its operations from each directory.
gpf script-export - CLI interface#
Write a Python script that repeats the successful operations from a recorded session.
gpf script-export [-h] [-o OUT] [--session SESSION] [--list] [--include-reads]
[--assert-hashes]
path
gpf script-export positional arguments#
path- A case file, a directory containing recorded sessions, or a recording file (.jsonl).
gpf script-export options#
-oOUT,--outOUT- Write the script here. Standard output otherwise.--sessionSESSION- Session to export. Use --list to show the available values. The default is the most recently active session.--list- List the available sessions, then exit.--include-reads- Also include read-only operations.--assert-hashes- Verify the case after each modifying operation.
Review workbench: gpf serve#
gpf serve starts the local review workbench for recorded operations and case
changes. The page shows the activity for the open case and lets a reviewer
approve or reject recorded work. Use gpf exhibit to create a portable review
artifact.
Start a local workbench for a workspace with:
gpf serve WORKSPACE
The default address is for local use. Require authentication when another host
can reach the service. Set --token or GPF_TOKEN to provide the required
authentication token.
gpf serve - CLI interface#
Review recorded operations and case changes under a directory. Use `gpf exhibit` to create a portable review file.
gpf serve [-h] [--host HOST] [--port PORT] [--token TOKEN] [--open] [--shutdown-on-stdin-eof]
[--compact-journals KEEP]
[workspace]
gpf serve positional arguments#
workspace- directory whose recorded work the workbench shows (default: current directory) (default:.)
gpf serve options#
--hostHOST- bind address (default: 127.0.0.1) (default:127.0.0.1)--portPORT- port (default: 8347) (default:8347)--tokenTOKEN- require bearer authentication for API requests (default: $GPF_TOKEN). A non-local address always requires authentication; localhost defaults to single-user access--open- open the workbench in the default browser once bound--shutdown-on-stdin-eof- stop when standard input closes--compact-journalsKEEP- before serving, reduce each stored operation history to its newest KEEP records
Agent server: gpf mcp#
gpf mcp starts the MCP tools for an AI
assistant. The server ships with every install. Registering it with Claude
Code, Codex, Cursor, or another client is covered in
Use gpf from an AI agent.
The loaded case remains available across related tool calls in one server
session.
gpf mcp
gpf mcp - CLI interface#
Start the gpf MCP server for an AI assistant.
gpf mcp [-h]
gpf mcp options#
Licensing: gpf license#
gpf license activates, reports, or deactivates a licensed installation. The
free edition does not require activation.
gpf license activate --key -
gpf license status
gpf license deactivate
gpf license - CLI interface#
``gpf license`` manages a licensed gpf installation.
gpf license [-h] {activate,status,deactivate} ...
gpf license options#
gpf license activate#
activate this machine, or print its Installation ID
gpf license activate [-h] [--key LICENSE_ID | --paste CREDENTIAL | --file LIC]
gpf license activate options#
gpf license status#
show license state
gpf license status [-h]
gpf license status options#
gpf license deactivate#
remove the stored credential and key
gpf license deactivate [-h]