CLI

Genalyzer provides a genalyzer command that mirrors every MCP tool as a grouped subcommand. It is the simpler surface for AI clients and scripted pipelines that prefer plain stdio + JSON over the MCP protocol.

Installation

pip install genalyzer[cli]

Like the MCP server, the CLI requires the native libgenalyzer library. See Installation for build instructions.

Running the CLI

genalyzer --version
genalyzer --help
genalyzer tools        # prints the 16 underlying MCP tool names

Every subcommand accepts --compact for single-line JSON output (default is pretty-printed) and emits the tool’s return dict on stdout.

Command reference

genalyzer

genalyzer: parallel surface to the MCP server for AI clients.

Every subcommand wraps a genalyzer.mcp tool, accepts the same parameters as kebab-case CLI flags, and emits the tool’s return dict as JSON on stdout. Use –compact for single-line JSON.

Usage

genalyzer [OPTIONS] COMMAND [ARGS]...

Options

--version: Show the version and exit.

fourier

Fourier-domain analysis.

Usage

genalyzer fourier [OPTIONS] COMMAND [ARGS]...

analyze

All-in-one spectral analysis: load data, compute FFT, and return metrics.

When plot=True, an annotated spectrum PNG is also written next to the input file.

Usage

genalyzer fourier analyze [OPTIONS]

Options

--npy-path <npy_path>: Required

--sample-rate <sample_rate>: Required

--nfft <nfft>

--num-tones <num_tones>

--max-harmonics <max_harmonics>

--window <window>

--ssb <ssb>

--wo <wo>

--plot, --no-plot

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

fa-metrics

Compute frequency analysis metrics from a pre-computed FFT .npy file.

Use this when you already have an FFT artifact and want metrics from it, for example in a sweep pipeline that reuses one FFT across many metric extractions.

Usage

genalyzer fourier fa-metrics [OPTIONS]

Options

--fft-npy-path <fft_npy_path>: Required

--sample-rate <sample_rate>: Required

--tone-freq <tone_freq>: Required

--max-harmonics <max_harmonics>

--wo <wo>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

fft

Compute FFT of time-domain data stored in a .npy or .csv file.

Args:: npy_path: Path to input .npy or .csv file containing time-domain samples. sample_rate: Sample rate in Hz. nfft: FFT size. Defaults to the length of the input data. output_path: Path to save the FFT result .npy file. Auto-generated if not provided.
Returns:: Dictionary with output_path, nfft, and sample_rate.

Usage

genalyzer fourier fft [OPTIONS]

Options

--npy-path <npy_path>: Required

--sample-rate <sample_rate>: Required

--nfft <nfft>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

generators

Synthetic waveform generators.

Usage

genalyzer generators [OPTIONS] COMMAND [ARGS]...

gaussian-noise

Generate AWGN samples and save to .npy.

Useful for NSD (noise spectral density) characterization and histogram Gaussian-fit tests.

Usage

genalyzer generators gaussian-noise [OPTIONS]

Options

--num-points <num_points>: Required

--mean <mean>

--std <std>

--seed <seed>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

ramp

Generate a linear ramp from start to stop and save to .npy.

Useful for DNL and INL characterization. The ramp covers the closed interval [start, stop].

Usage

genalyzer generators ramp [OPTIONS]

Options

--num-points <num_points>: Required

--start <start>

--stop <stop>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

real-tone

Generate a real-valued sinusoidal test tone and save to .npy.

Use this for real-only ADC characterization. For complex (IQ) ADCs, prefer generate_test_tone.

Usage

genalyzer generators real-tone [OPTIONS]

Options

--num-points <num_points>: Required

--sample-rate <sample_rate>: Required

--tone-freq <tone_freq>: Required

--amplitude <amplitude>

--phase <phase>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

test-tone

Generate a synthetic complex sinusoidal test tone and save to a .npy file.

Args:: num_points: Number of samples to generate. sample_rate: Sample rate in Hz. tone_freq: Tone frequency in Hz. amplitude: Amplitude (0.0 to 1.0, default 0.9). output_path: Path to save the .npy file. Auto-generated if not provided.
Returns:: Dictionary with output_path, num_points, sample_rate, and tone_freq.

Usage

genalyzer generators test-tone [OPTIONS]

Options

--num-points <num_points>: Required

--sample-rate <sample_rate>: Required

--tone-freq <tone_freq>: Required

--amplitude <amplitude>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

histogram

Code-density histogram tools.

Usage

genalyzer histogram [OPTIONS] COMMAND [ARGS]...

analyze

Compute histogram analysis metrics from integer code samples.

Returns the four native gn.hist_analysis summary fields: sum (total sample count), first_nz_index / last_nz_index (first/last non-empty bin), and nz_range (span of populated codes). When plot=True, also render a histogram PNG next to the input file.

Usage

genalyzer histogram analyze [OPTIONS]

Options

--npy-path <npy_path>: Required

--nbits <nbits>: Required

--code-format <code_format>

--plot, --no-plot

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

compute

Compute the code histogram of integer samples.

Args:: npy_path: Path to .npy/.csv with integer code samples. nbits: Bit depth of the quantizer that produced the data. code_format: “twos_complement” (default) or “offset_binary”. output_path: Path to save histogram .npy. Auto-generated if omitted.

Usage

genalyzer histogram compute [OPTIONS]

Options

--npy-path <npy_path>: Required

--nbits <nbits>: Required

--code-format <code_format>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

linearity

DNL / INL tools.

Usage

genalyzer linearity [OPTIONS] COMMAND [ARGS]...

analyze-dnl

All-in-one DNL analysis from a raw code-samples .npy file.

Loads samples, builds a histogram, computes DNL, returns summary metrics (dnl_max, dnl_min, dnl_abs_max). When plot=True, also renders a DNL PNG.

Usage

genalyzer linearity analyze-dnl [OPTIONS]

Options

--npy-path <npy_path>: Required

--nbits <nbits>: Required

--signal-type <signal_type>

--code-format <code_format>

--plot, --no-plot

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

analyze-inl

All-in-one INL analysis from a raw code-samples .npy file.

Usage

genalyzer linearity analyze-inl [OPTIONS]

Options

--npy-path <npy_path>: Required

--nbits <nbits>: Required

--signal-type <signal_type>

--code-format <code_format>

--fit <fit>

--plot, --no-plot

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

compute-dnl

Compute DNL from a histogram .npy produced by compute_histogram.

Args:: hist_npy_path: Path to a .npy histogram. signal_type: “tone” (default) or “ramp”. output_path: Path to save DNL .npy. Auto-generated if omitted.

Usage

genalyzer linearity compute-dnl [OPTIONS]

Options

--hist-npy-path <hist_npy_path>: Required

--signal-type <signal_type>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

compute-inl

Compute INL from a DNL .npy produced by compute_dnl.

Args:: dnl_npy_path: Path to a .npy DNL array. fit: “best_fit” (default) or “end_point” (maps to END_FIT). output_path: Path to save INL .npy. Auto-generated if omitted.

Usage

genalyzer linearity compute-inl [OPTIONS]

Options

--dnl-npy-path <dnl_npy_path>: Required

--fit <fit>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

quantize

Quantize a time-domain waveform to N-bit codes, saving as .npy.

Args:

npy_path: Path to input .npy or .csv time-domain samples. bits: Number of quantizer bits (e.g. 12, 14, 16). fullscale: Full-scale range of the quantizer (default 1.0). noise: Optional additive-noise standard deviation passed to the native

gn.quantize() call (default 0.0 — ideal quantizer).

output_path: Path to save the quantized .npy. Auto-generated if omitted.

Returns:

Dictionary with output_path, bits, and fullscale.

Usage

genalyzer quantize [OPTIONS]

Options

--npy-path <npy_path>: Required

--bits <bits>: Required

--fullscale <fullscale>

--noise <noise>

--output-path <output_path>

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

tools

Print the 16 MCP tool names (one per line).

Usage

genalyzer tools [OPTIONS]

waveform

Time-domain waveform tools.

Usage

genalyzer waveform [OPTIONS] COMMAND [ARGS]...

analyze

All-in-one time-domain waveform analysis.

Currently identical to compute_waveform_stats; plot=True renders a scope-style PNG of the first 10_000 samples next to the input file.

Usage

genalyzer waveform analyze [OPTIONS]

Options

--npy-path <npy_path>: Required

--plot, --no-plot

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

stats

Compute time-domain statistics (min/max/mid/range/avg/rms/rmsac) on a real waveform.

Complex inputs are reduced to their real part before analysis.

Usage

genalyzer waveform stats [OPTIONS]

Options

--npy-path <npy_path>: Required

--compact, --pretty: Emit single-line JSON instead of pretty-printed.

Examples

The three workflow patterns documented in MCP Workflows have direct CLI equivalents. Each example uses jq to chain output paths between steps.

Simulate-and-verify a 12-bit converter

TONE=$(genalyzer generators real-tone \
    --num-points 8192 --sample-rate 250e6 --tone-freq 30e6 --amplitude 0.9 \
    --compact | jq -r .output_path)

Q=$(genalyzer quantize --npy-path "$TONE" --bits 12 --fullscale 2.0 --compact \
    | jq -r .output_path)

genalyzer fourier analyze --npy-path "$Q" --sample-rate 250e6 \
    --window blackman_harris --ssb 3

Analyze a hardware capture

genalyzer fourier analyze \
    --npy-path /tmp/adc_capture.npy \
    --sample-rate 250e6 \
    --window blackman_harris \
    --ssb 12 \
    --plot

Sweep in a pipeline

for f in 10e6 30e6 60e6 90e6; do
    TONE=$(genalyzer generators test-tone --num-points 8192 --sample-rate 250e6 \
           --tone-freq "$f" --amplitude 0.9 --compact | jq -r .output_path)
    genalyzer fourier analyze --npy-path "$TONE" --sample-rate 250e6 \
        --window blackman_harris --ssb 3 --compact \
        | jq "{tone_freq: $f, sfdr, snr}"
done

Exit codes

Situation	Exit
Tool returns a result dict	`0`
Tool returns `{"error": "..."}`	`0` (stdout JSON carries the error for the agent)
Unhandled exception inside the tool	`1` (stdout JSON with an `error` key)
Click detects bad arguments (missing flag, wrong type)	`2`