CLI Reference

Use this chapter when you already know you need the tdse command-line tool and want the shortest path to the right command, the stable output fields for automation, or the exact syntax for a specific verb.

Purpose

Use the CLI to verify SDK identity, run Circuit SDK workflows, produce Builder-ready artifacts, and capture profiler evidence without writing host code.

Prerequisites

• A built tdse executable on PATH or addressed by full path.
• Writable output locations for --out-* files.
• Input files or inline text for the selected command family.

5-Minute Path

tdse sdk version --json-out -
tdse circuit caps --out-caps caps.json --json-out -
tdse profiler quick --out-json profile.json --json-out -

Expected Output Sample:

tdse sdk version: success
tdse circuit caps: success
tdse profiler quick: success

Production Path

In CI, pin every command line, emit --json-out - or a JSON artifact, archive numeric outputs, and record the exact SDK version. Treat command stdout/stderr as evidence only when paired with the stable JSON envelope.

Parameter Cookbook

Parameter	Applies To	Rule
--json-out	most commands	Always set for automation.
--out-data	circuit outputs	Use a writable file or -.
--ports	circuit matrix/series/probe	Keep ordering stable.
--out-json	profiler/workflow outputs	Archive as release evidence.

Failure Modes

Failure	Usual Cause	First Check
command not found	CLI not on PATH	Run with the full executable path.
output open failed	target directory missing	Create the directory or use -.
parse failed	malformed input file	Reduce to one minimal input case.

Troubleshooting

• Run tdse sdk version --json-out - first.
• Add --json-out - to capture machine-readable error fields.
• Re-run circuit commands with one port and one frequency before widening.

Validation Checklist

• Version command output archived.
• Representative circuit command returns success.
• Profiler report validates or has an accepted explanation.
• Output files are written outside the repository root.

How To Use This Chapter

Most readers use this chapter in one of two ways:

• to confirm which command family to use: sdk, circuit, or profiler
• to look up exact flags, output files, and machine-readable fields

If you are still getting your first model running, start with Getting Started and come back here when you need exact command syntax.

Before You Start

• A successful build that produces the tdse executable.
• A writable output directory for --out-* targets.
• Representative input data for the path you want to exercise.

cmake --build build --target tdse

First Confidence Check

For the general SDK installation and first-run path, see Installation.

Use these three commands to confirm that the CLI routes correctly, that Circuit SDK is available, and that the profiler can emit a report:

tdse sdk version --json-out -
tdse circuit caps --out-caps /tmp/caps.json --json-out -
tdse profiler quick --out-json ./tdse_profile_report.json --json-out -

Expected output sample:

tdse sdk version: success
tdse circuit caps: success
tdse profiler quick: success

Choose A Command Family

Use this table before dropping into the full reference:

If you need to...	Use...	Primary outputs
confirm binary and SDK identity	tdse sdk version	version metadata JSON
inspect or convert circuit-domain input	tdse circuit ...	netlists, matrix CSV, probe CSV, JSON envelopes
build runtime-ready operator pack	tdse workflow ...	.pack binary, passivity/round-trip JSON
inspect or fully validate a runtime pack	tdse pack ...	Runtime Pack inspection JSON
benchmark runtime behavior or derive a runtime plan	tdse profiler ...	profiler report JSON, summary Markdown, matrix CSV

Typical starting points:

• PSS/E RAW case -> circuit raw-to-netlist
• circuit netlist -> circuit matrix, series, or probe
• netlist to deployable model -> tdse workflow pack
• backend or route uncertainty -> profiler calibrate, sweep, validate, explain, diff
• profiler quick|calibrate|sweep
• profiler validate|explain|diff|tables

Most Common Workflows

If you want the shortest path from intent to command, start here:

Goal	First command	Then usually do this
prove the binary and installation are sane	tdse sdk version --json-out -	move to Getting Started
convert a RAW case	tdse circuit raw-to-netlist	run matrix on the generated netlist
generate Builder-facing matrix data	tdse circuit matrix	move to Builder and Data Contracts
inspect source-side waveforms	tdse circuit series	compare against expected circuit behavior
inspect internal nodes or branches	tdse circuit probe	use Troubleshooting if values look wrong
build a deployable operator pack from a netlist	tdse workflow pack	load pack in Runtime Lifecycle
import NBM manifest to operator pack	tdse workflow nbm	verify passivity/round-trip in JSON output
inspect or validate an existing runtime pack	tdse pack inspect --json <pack.bin>	use tdse pack validate --json <pack.bin> before model create
capture a baseline performance report	tdse profiler quick	follow with validate, explain, diff, or tables

Use Circuit SDK when you need the circuit-domain meaning behind a command. Use this chapter when you need exact flags, outputs, and stable fields.

Common Automation Rules

These rules make CLI usage much more predictable in scripts and CI:

• always set --json-out for machine parsing
• archive the exact input identity for circuit and profiler runs
• keep port ordering stable across repeated matrix and series generation
• archive the exact frequency grid when generating Builder-facing matrix data
• for profiler runs, prefer emitting JSON, Markdown, and CSV together

Parameter quick reference:

Parameter	Where it appears	Practical rule	Why it matters
--json-out	most public commands	always set in automation	gives stable JSON output that scripts can parse
--out-data	circuit matrix/series/probe	point to a writable file or -	captures primary numeric output
--ports	circuit matrix/series/probe	keep ordering stable across replays	output shape depends on port order
--w0-radps, --dw-radps, --nfreq	circuit matrix	archive the exact grid	frequency sweep identity must be reproducible
--out-json, --out-md, --out-csv	profiler commands	emit all three in release records	JSON is best for automation, Markdown and CSV are easier to review
--min-coverage	profiler validate	pin the threshold in CI	prevents silent report drift

When The CLI Fails

Start with these checks before reading the deeper reference material:

• run tdse sdk version --json-out - to confirm you are using the expected binary
• add --json-out - so failure details remain visible in shell-only logs
• reduce circuit failures to the smallest netlist, one port, and one frequency when possible
• compare current profiler output against a known-good report with tdse profiler diff

Production And CI Path

Use this short path when you are qualifying a build or capturing release evidence:

1. run tdse sdk version --json-out - and archive the version JSON
2. run one representative circuit command with --json-out
3. run one representative profiler command with --out-json, --out-md, and --out-csv
4. rerun tdse profiler validate, explain, diff, or tables on the saved report when needed
5. archive exit codes and artifact paths alongside the input identity

Related Docs

• Getting Started
• Circuit SDK
• Profiler
• Troubleshooting
• C API Reference

Reference: Commands

Command Summary

Command	Purpose	Key options
sdk version	Report CLI/SDK/git/runtime version metadata	--json-out
circuit caps	Emit backend capability Markdown and build-feature JSON	--out-caps, --out-build-features, --json-out
circuit raw-to-netlist	Convert PSS/E RAW input into circuit-compatible netlist with base-frequency validation	--raw-kind, --raw, --out-netlist, --out-report-json, --json-out
circuit matrix	Compute Y or Z matrix over a frequency grid and emit CSV	--netlist-kind, --matrix, --ports, --w0-radps, --dw-radps, --nfreq, --out-data, --json-out
circuit series	Compute VOC or ISC source-side time series	--netlist-kind, --series, --ports, --method, --dt, --steps, --out-data, --json-out
circuit probe	Compute AC or transient probe outputs	--domain, --netlist-kind, --observe, --observe-source, --out-data, --json-out
circuit nbm	Import Netlist Boundary Manifest and emit resolved named ports	--manifest, --netlist-override, --no-sha256-check, --out-json, --json-out
workflow pack	Compile netlist, frequency sweep, and build validated operator pack	--netlist-kind, --netlist, --out-pack, --matrix, --ports, --dt, --nh, --nfreq, --auto-sweep, --json-out
workflow nbm	Import NBM manifest and build validated operator pack	--manifest, --out-pack, --matrix, --dt, --nh, --json-out
workflow yz	Build pack from in-memory Y/Z matrix (stdin)	--matrix-kind, --nports, --freqs-hz, --matrix-ri-stdin, --out-pack, --dt, --nh, --json-out
pack inspect	Inspect Runtime Pack metadata without creating a runtime model	--json, <pack.bin>
pack validate	Validate Runtime Pack by creating and releasing a runtime model	--json, <pack.bin>
profiler quick	Quick benchmark pass	--out-json, --out-md, --out-csv, --json-out
profiler calibrate	Calibrated benchmark with route-policy derivation	--out-json, --out-md, --out-csv, --json-out
profiler sweep	Full parameter sweep benchmark	--out-json, --out-md, --out-csv, --json-out
profiler validate	Validate a profiler report against coverage thresholds	--min-coverage, --json-out
profiler explain	Explain one shape from a profiler report	--np, --nh, --dtype, --json-out
profiler diff	Diff two profiler reports	--out-md, --json-out
profiler tables	Generate route/case tables from a profiler report	--out-route-md, --out-matrix-md, --json-out
profiler irc-scan	Advanced IRC scan for specialized workflows	--scan-prefix-counts, --scan-growth-values, --scan-input, --out-recommend-json, --json-out

SDK Commands

sdk version — Report CLI, SDK, git, and runtime version metadata.

Minimal replay:

tdse sdk version --json-out -

Documented data keys:

• cli_version
• sdk_version
• git_commit
• runtime_version
• runtime_version_major
• runtime_version_minor
• runtime_version_patch

Circuit SDK Commands

circuit caps — Emit backend capability Markdown and optional build-feature JSON.

Minimal replay:

tdse circuit caps \
  --out-caps ./circuit_caps.md \
  --out-build-features ./circuit_build_features.json \
  --json-out -

Documented data keys:

• backend_count
• caps_target
• build_features_target

Capability Markdown is operator-facing, while build-features JSON is machine-readable.

circuit raw-to-netlist — Convert PSS/E RAW input into a circuit-compatible netlist and run base-frequency validation in the same command path.

Minimal replay:

tdse circuit raw-to-netlist \
  --raw-kind file --raw case.raw \
  --out-netlist ./case_from_raw.cir \
  --out-report-json ./raw_report.json \
  --json-out -

Documented data keys:

• source_kind
• strict
• output_target
• report_target
• netlist_bytes
• report_required_bytes
• validation_pass
• import_report
• summary

import_report and summary are the contract anchors for conversion count diagnostics and base frequency validation outcomes.

Byte-size semantics: netlist_bytes and report_required_bytes are payload bytes, excluding trailing C-string null terminators.

circuit matrix — Compute Y or Z matrix data over a requested frequency grid.

Minimal replay:

tdse circuit matrix \
  --netlist-kind file --netlist case.cir \
  --matrix y --ports "1,0;2,0" \
  --w0-radps 377 --dw-radps 0 --nfreq 1 \
  --out-data ./matrix.csv \
  --json-out -

Required options:

• --netlist-kind <file|text|stdin>
• --matrix <y|z>
• --ports <p0p,p0n;p1p,p1n;...>
• --w0-radps <w0>
• --dw-radps <dw>
• --nfreq <N>

Common optional output:

• --out-data <path|->
• --json-out <path|->

DC endpoint options:

• --dc-policy <mode>
• --dc-extrapolate-points <N>

DC policy notes:

• --w0-radps may be 0 or any positive finite value
• CLI default is --dc-policy exact_dc_then_fallback
• regularized_exact_dc keeps the regularized 0Hz solve behavior as the primary endpoint strategy
• extrapolate_from_positive replaces the 0Hz sample with a surrogate endpoint fitted from the first positive-frequency samples; it is intended for plotting and Builder-facing smooth endpoints, not as an exact DC proof point
• exact_dc_then_fallback first attempts an exact 0Hz solve with DC element semantics; if that endpoint is singular or otherwise unusable and positive-frequency samples exist, it falls back to the same surrogate endpoint strategy
• when --w0-radps 0 and --dc-policy extrapolate_from_positive, use --nfreq >= 2

Documented data keys:

• matrix_kind
• netlist_kind
• np
• nfreq
• output_target

circuit series — Compute VOC or ISC source-side time series.

Minimal replay:

tdse circuit series \
  --netlist-kind file --netlist case.cir \
  --series voc --ports "1,0" \
  --method transient --dt 1e-4 --steps 64 \
  --out-data ./series.csv \
  --json-out -

Required options:

• --netlist-kind <file|text|stdin>
• --series <voc|isc>
• --ports <p0p,p0n;...>
• --method <tone|ifft|transient>
• --dt <dt>
• --steps <N>

Method-specific note:

• --nfft is required when --method=ifft

Documented data keys:

• response_kind
• netlist_kind
• method
• np
• steps
• dt
• output_target

circuit probe - Compute AC or transient probe outputs.

Required options:

• --domain <ac|transient>
• --netlist-kind <file|text|stdin>

Minimal AC replay:

tdse circuit probe \
  --domain ac --netlist-kind file --netlist case.cir \
  --observe "v(1,0)" --observe-source argument \
  --ac-excitation small_signal \
  --sweep-kind list --freq-list-hz 50,60 \
  --out-data ./probe_ac.csv \
  --json-out -

Minimal transient replay:

tdse circuit probe \
  --domain transient --netlist-kind file --netlist case.cir \
  --observe "v(1,0)" --observe-source argument \
  --method transient --dt 1e-4 --steps 64 \
  --out-data ./probe_tr.csv \
  --json-out -

Transient-specific options:

• --method <tone|ifft|transient>
• --dt <dt>
• --steps <N>
• optional --nfft <N>
• optional --t0 <t0>

AC-specific options:

• optional --ac-excitation <small_signal|operating_point>
• --sweep-kind <from_netlist|lin|dec|oct|list>
• sweep arguments matching the selected sweep kind

Probe options:

• --observe "v(1,0);i(r1)"
• --observe-source <argument|netlist|argument_or_netlist|auto>

Documented data keys:

• domain
• netlist_kind
• probe_source
• probe_count
• method and steps for transient mode
• sweep_kind, excitation_mode, and nfreq for AC mode
• output_target

Profiler Benchmark Commands (quick, calibrate, sweep)

Benchmark runtime shapes and produce route-policy artifacts.

Common output options:

• --out-json <report.json>
• --out-md <summary.md>
• --out-csv <matrix.csv>
• --json-out <envelope.json> for unified CLI status envelope

Common workload controls:

• --np <N>
• --nh <N>
• --dtype <32|64>
• --steps <N>
• --warmup <N>
• --repeats <N>

Profiler Utility Commands (validate, explain, diff, tables, irc-scan)

Validation:

• tdse profiler validate <report.json> [--min-coverage X]

Explain one shape:

• tdse profiler explain <report.json> --np <N> --nh <N> [--dtype 64]

Diff two reports:

• tdse profiler diff <old_report.json> <new_report.json> [--out-md <diff.md>]

Generate route/case tables:

• tdse profiler tables <report.json> --out-route-md <route.md> --out-matrix-md <matrix.md>
• all profiler verbs also support --json-out <envelope.json> for machine-readable status

profiler irc-scan — Advanced IRC scan for specialized workflows:

• tdse profiler irc-scan
• --scan-prefix-counts ...
• --scan-growth-values ...
• --scan-input random|lowpass|step_ring|trace
• --out-recommend-json <recommend.json>

Deep Reference: Output Formats and Stable Fields

Use this section when you parse CLI artifacts directly in automation or tooling. If you only need to run commands interactively, the command reference above is usually enough.

Common JSON Envelope

When --json-out is enabled, the CLI writes a completion envelope with these stable top-level keys:

• group
• action
• status
• exit_code
• message
• data

Parsing guidance:

• use group and action to determine which command completed
• use status, exit_code, and message for command outcome handling
• parse data according to the command family and the corresponding output shape
• accept undocumented extra keys conservatively rather than failing hard on their presence
• do not treat undocumented nested keys inside data as a long-term contract unless another public guide section says so explicitly

For profiler commands, --json-out is a command-level envelope emitted by the unified tdse router (group="profiler"), so automation can consume success/failure status consistently across circuit and profiler families.

Output Artifacts

Circuit SDK. Primary circuit-sdk outputs:

• converted netlist
• validation report JSON
• matrix or probe CSV
• command completion JSON envelope

Use these as integration records before handoff to Builder and Runtime.

Profiler. Primary profiler outputs:

• profiler report JSON (authoritative machine-readable surface)
• optional summary Markdown
• optional matrix CSV
• runtime plan section for tdse_backend_apply_plan(...)

Cross-Family Handoff. Treat TDSE CLI outputs as one handoff chain:

1. circuit-domain artifacts establish model and signal validity
2. profiler artifacts establish route and policy validity
3. runtime consumes stable plan information only after both are accepted

Authoritative vs Summary.

• authoritative:
  • circuit and profiler JSON outputs
  • profiler schema-backed report
• summary:
  • Markdown and human review tables
  • CSV convenience outputs for analysis

Command Data Shapes

sdk version fields:

• cli_version
• sdk_version
• git_commit
• runtime_version
• runtime_version_major
• runtime_version_minor
• runtime_version_patch

circuit caps documented data fields:

• backend_count
• caps_target
• build_features_target

circuit raw-to-netlist documented fields:

• source_kind
• strict
• output_target
• report_target
• netlist_bytes
• report_required_bytes
• validation_pass
• import_report
• summary

Matrix Output (Y / Z). CLI CSV header:

freq_index,freq_radps,row,col,re,im

Parsing contract:

• one row per frequency / matrix-row / matrix-column tuple
• freq_index is zero-based
• freq_radps is the physical angular frequency for that row
• row and col are zero-based port indices
• re and im store the complex value
• frequency-major ordering

In-memory C API layout:

• frequency-major row-major
• packed as out[2*(k*np*np + row*np + col) + {0,1}]

Builder handoff note:

• this is the same ordering expected when the matrix is exposed through tdse_builder_cplx_mat_view_t

VOC / ISC Time-Series Output. CLI CSV header:

step,time,port,value

Parsing contract:

• one row per time step and port
• step is zero-based
• time = t0 + step * dt
• port is the zero-based port index
• value is the scalar VOC or ISC sample
• step-major ordering

In-memory C API layout:

• step-major row-major
• out_values[step*np + port]

Integration note:

• CLI JSON is metadata only; the sequence payload contract is the CSV shape above or the in-memory layout above

Transient Probe Output. CLI CSV header:

step,time,probe,value

Parsing contract:

• one row per time step and resolved probe
• probe is the zero-based resolved probe index
• the mapping from probe index to expression depends on CLI --observe order or netlist probe order

In-memory C API layout:

• step-major row-major
• out_values[step*nprobe + probe]

AC Probe Output. CLI CSV header:

freq_index,freq_hz,probe,re,im

Parsing contract:

• one row per frequency sample and probe
• freq_index is zero-based
• freq_hz is the physical frequency in Hz
• probe is the zero-based resolved probe index
• re / im store the complex probe response
• frequency-major ordering

In-memory C API layout:

• frequency-major row-major with RI interleaving
• out_values_ri[2*(k*nprobe + p) + 0] = Re(X_p(f_k))
• out_values_ri[2*(k*nprobe + p) + 1] = Im(X_p(f_k))

Unit note:

• AC probe sweep files use Hz, not rad/s

Region Preparation and Region-Compute Report. tdse_circuit_prepare_region(...) can return a machine-readable JSON report through out_report_json.

For machine integration, the primary shape contract is no longer JSON-only:

• region preparation returns required_ports_len plus optional out_ports
• matrix calls return result.shape plus optional out_resolved_ports
• series calls return result.shape plus optional out_resolved_ports
• probe calls return result.shape

Treat the JSON report as audit/debug metadata, not the only source of shape information.

Stable top-level keys for this release:

• report_version
• summary
• boundary
• shape
• resolved_ports
• issues

Parsing guidance:

• require report_version == 2
• treat the key set above as the documented top-level contract for this release
• tolerate additional undocumented keys conservatively
• use result.shape, result.required_*, and optional out_resolved_ports as the primary in-memory sizing contract

Top-level shape:

{
  "report_version": 2,
  "summary": {},
  "boundary": {},
  "shape": {},
  "resolved_ports": [],
  "issues": []
}

summary — operation metadata. Common keys include: operation, accepted, requested_node_count, region_node_count, region_element_count, component_count, boundary_node_count, port_count, topology_hash, and parameter_hash. The operation field identifies which phase emitted the report (for example, prepare_region).

boundary — region boundary structure. Contains components, where each component holds boundary_nodes, reference_node, and ports.

shape — dimension and layout contract. Always includes port_count and layout. Matrix reports add required_values_len, w0, dw, nfreq. Series reports add required_values_len, dt, steps. Preparation reports include required_ports_len.

resolved_ports — array of [node_p, node_n] pairs. Each entry is a canonical SPICE node label string ("0" for ground, retained name forms when available, numeric token otherwise). Hosts must not interpret these strings as internal node indices.

Profiler Canonical JSON Report. Primary machine-readable artifact:

• tdse_profile_report.json

Runtime-facing expectations:

• schema_version == "tdse_profile_report_v1"
• concrete fingerprint fields
• policy.rules
• runtime_plan

Profiler --json-out Envelope. Profiler envelope data is currently an empty object {} and is intended as a stable status contract:

• group: always profiler
• action: resolved profiler action (quick, calibrate, validate, diff, etc.)
• status: ok or error
• exit_code: process exit code
• message: short completion/failure summary

runtime_plan Contract. runtime_plan is the profiler output intended for TDSE Core consumption through tdse_backend_apply_plan(...).

At minimum, it must provide:

• a default backend choice
• scenario-based selections for relevant shape signatures

Human-Review And Debug Outputs

• Markdown summary and route tables are human-review surfaces
• CSV matrices are analysis/audit surfaces
• runtime consumption should rely on JSON contracts only

NPORT Debug CSV / JSON. Debug CSV shape:

# type=Y,nports=2,z0=50
freq_hz,row,col,re,im
1000,0,0,1.0,0.0
1000,0,1,0.0,0.0
1000,1,0,0.0,0.0
1000,1,1,2.0,0.0

Rules:

• the file must contain the full N x N matrix at each frequency
• row and col are zero-based
• type should be Y or Z

Debug JSON shape:

{
  "nports": 2,
  "type": "Y",
  "z0": 50,
  "freq_hz": [1000, 2000],
  "mats_ri": [
    [[1, 0], [0, 0], [0, 0], [2, 0]],
    [[3, 0], [0, 0], [0, 0], [4, 0]]
  ]
}

Rules:

• freq_hz[k] and mats_ri[k] must have matching outer lengths
• each mats_ri[k] can be either:
  • a flat row-major list of N*N complex pairs, or
  • a nested N x N list of complex pairs

Integrator Guidance. Recommended parser behavior:

• branch on group and action
• validate documented keys and headers
• ignore unknown extra keys conservatively
• archive artifact paths named in output_target, caps_target, build_features_target, report_target, and profiler report output options

Exit Codes

The CLI maps outcomes into stable process exit categories:

• 0: success
• 2: CLI argument shape error
• 10: invalid argument
• 11: parse failure
• 12: I/O failure
• 13: unsupported operation
• 14: singular solve
• 15: internal failure
• 16: backend unavailable
• 20: strict validation failure

Both command families (circuit and profiler) remain automation-friendly:

• nonzero code on failure family
• machine-readable completion payload via --json-out when available
• command-scoped stable fields documented in the output contracts section above