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 the installed product and authorization state, inspect Runtime Packs, and run TDSE Circuit workflows without writing host code.

The complete customer installation presents the primary executable as tdse.exe on Windows and tdse on Linux. When TDSE Circuit is included, that executable exposes the commands appropriate to the installed products. Customer automation should use tdse; internal target names do not define additional commands or packages.

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 doctor
tdse version --json-out -

Expected Output Sample:

TDSE Runtime     Included and authorized
Builder          Included with Runtime
Readiness        READY

Production Path

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

Parameter Cookbook

Failure Modes

Troubleshooting

• Run tdse doctor --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

• Doctor report archived.
• Representative circuit command returns success.
• CPU benchmark matrix output is archived.
• Output files are written outside the repository root.

How To Use This Chapter

Most readers use this chapter in one of two ways:

• to choose between the default doctor, pack, and circuit tasks
• 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.

python tools/tdse_build.py build --preset circuit --target tdse_full_cli

First Confidence Check

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

Start with the one command that summarizes the installed composition, authorization boundary, and Runtime readiness:

tdse doctor

Expected output sample:

TDSE Runtime     Included and authorized
Builder          Included with Runtime
Readiness        READY

Choose A Command Family

Use this table before dropping into the full reference:

Typical starting points:

• PSS/E RAW case -> circuit import --format psse_raw -> ModelSpace case
• ModelSpace case -> circuit matrix, series, or probe
• ModelSpace to deployable pack -> tdse workflow prepare
• engineering benchmark or IRC study -> tdse help advanced

Most Common Workflows

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

Use TDSE Circuit 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 CPU performance runs, archive the matrix JSON and run manifest; the matrix records the topology-derived thread and row plan

Parameter quick reference:

When The CLI Fails

Start with these checks before reading the deeper reference material:

• run tdse doctor --json-out - to capture the complete first-response view
• 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 the compact matrix rows directly in the calling application or benchmark harness

Production And CI Path

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

1. run tdse doctor --json-out - and archive the readiness JSON
2. run one representative circuit command with --json-out
3. use tdse help advanced only when the qualification procedure calls for it
4. archive the output, exit code, and input identity

Related Docs

• Getting Started
• TDSE Circuit
• Profiler
• Troubleshooting
• C API Reference (SDK source: docs/api-reference/c-api.md)

Reference: Commands

Command Summary

Product and License Commands

doctor — Answer four separate questions in one report: what is installed, whether its identity matches the loaded Runtime binary, what is authorized, and what is available on this machine. It combines those into local readiness but never turns readiness into a formal qualification claim.

tdse doctor --json-out -

When the OEM integration uses a provider library, it can be selected with --authorization-provider <path>, TDSE_AUTHORIZATION_PROVIDER_LIBRARY, or an optional standard installation location. These are trusted OEM/support diagnostic paths, not ways to select a different product or license file. An enforced build still fails closed when the selected provider is absent, fails, or denies the capability.

Stable data keys are schema, installation, products, builder, authorization_provider, build_features, backend_registry, qualification, readiness, and next_action. Each product row contains id, name, included, local_availability, and authorization.

version — Report CLI, release, git, and Runtime version metadata.

Minimal replay:

tdse version --json-out -

Documented data keys:

• cli_version
• release_version
• git_commit
• runtime_version
• runtime_version_major
• runtime_version_minor
• runtime_version_patch

tdse runtime version remains as a compatibility spelling. New automation should use the shorter tdse version.

Commercial license inspection belongs to the separately delivered TDSE or OEM authorization provider. The numerical Runtime CLI deliberately has no license file, public-key, SKU, or Preview-policy commands.

TDSE Circuit 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 matrix — Compute Y or Z matrix data over a requested frequency grid.

Minimal replay:

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

Required options:

• --case <case.json>
• --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
• case_format
• np
• nfreq
• output_target

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

Minimal replay:

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

Required options:

• --case <case.json>
• --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
• case_format
• method
• np
• steps
• dt
• output_target

circuit probe - Compute AC or transient probe outputs.

Required options:

• --domain <ac|transient>
• --case <case.json>

Minimal AC replay:

tdse circuit probe \
  --domain ac --case case.json \
  --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 --case case.json \
  --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_study|lin|dec|oct|list>
• sweep arguments matching the selected sweep kind

Probe options:

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

Documented data keys:

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

Runtime Performance Benchmark

tdse benchmark --device cpu|gpu is the only formal Runtime performance command. --device defaults to cpu; a requested device must be available and qualified because the command never falls back to another device.

• CPU matrix: np={1,2,4,8,16,32,64,128} x nh={512,1024,2048} x dtype={32,64}. It requires the approved CPU_BLAS/OpenBLAS provider.
• GPU default: the eight-row local-regression diagnostic profile. The 48-row Cartesian matrix requires explicit --matrix-profile formal and --evidence-class formal. Both require a valid CUDA product provider and record GPU-resident and CPU-resident integration evidence.
• --device-ids 0,2,5,7 selects an ordered GPU subset; the first ordinal is the root GPU. Omitting it keeps the single-GPU default on ordinal 0.
• --np, --nh, and --dtype select one synthetic shape.
• --pack <runtime.pack> is CPU-only, runs the same operation on a real pack, and cannot be combined with synthetic shape overrides.
• The configured thread count is all physical cores inside the selected host resource boundary. Use --thread-cap, --cpu-set, or Linux-only --numa-node to narrow it.
• Output rows are contiguous complete-row tasks balanced across NUMA x LLC locality domains. The approved provider disables split-K.
• Measurement controls are --min-steps, --max-steps, --target-repeat-ms, --warmup-steps, and --repeats.
• CPU and explicit GPU formal runs use exactly 64 untimed warmup calls per row and repeat; the default GPU regression owns a fixed 64-step warmup. See Recommended Benchmark Warmup Settings.
• The formal measured-step budget targets approximately 250 ms per repeat, bounded to 64 through 1,000,000 steps, and runs seven repeats. Standard deviation, CV, MAD, drift, min, max, median, and p95 are reported directly; variability does not trigger retries or a qualitative status.
• --tail-samples N enables a separate individual-step tail pass; --deadline-ns N is valid only with a positive sample count.
• --progress 1|0 controls host-side stderr progress emitted between rows, never inside a timed step.

--output writes the matrix artifact. --json-out writes the unified CLI completion envelope. See Runtime Performance Benchmark.

profiler irc-scan remains an unrelated advanced Builder IRC analysis command. It does not configure CPU benchmark threads.

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

TDSE Circuit. Primary Circuit outputs:

• imported ModelSpace case JSON
• validation report JSON
• matrix or probe CSV
• command completion JSON envelope

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

Runtime benchmark. The primary performance output is the compact matrix JSON from tdse benchmark --device cpu|gpu.

Cross-Family Handoff. Circuit artifacts establish model validity; the matrix artifact records independent timing, topology, row ownership, provider identity, and repeat statistics. Embedded Runtime execution leaves provider state under host ownership.

Authoritative vs Summary.

• authoritative: circuit JSON outputs and the compact profiler JSON outputs
• human-readable summaries are derived from those JSON files

Command Data Shapes

version fields:

• cli_version
• release_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

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 ModelSpace observation 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.

CPU performance JSON. The matrix contains one measured row per requested shape, its topology-derived task plan, correctness receipt, and repeat statistics. It is evidence, not an executable Runtime plan.

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, and report_target

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

All command families 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