EulerNPU CLI Reference

Follows the common CLI convention of the eulerwa product family. All user-facing messages are i18n-enabled (ko by default; en/zh/ja/es supported).

한국어 버전 / Korean version: cli.html

Entry Point

Single executable: eulernpu

All features are subcommands:

eulernpu [--lang ko|en|zh|ja|es] <command> [args...]

Hyphen-combined commands (eulernpu-info, eulernpu-compile, etc.) are not supported.

Global `--lang` Option

`--lang ko|en|zh|ja|es`

Set output language. Applies to help text, log messages, error summaries, and success output. Default: ko.

Supported languages:

ko — 한국어 (default)
en — English
zh — 中文 (简体)
ja — 日本語
es — Español

Not translated (always unchanged): command/option names, op/backend/dtype names, JSON keys, spec keys, validator rule codes.

# Korean output (default)
eulernpu validate examples/tiny_mlp/spec.yaml

# English output
eulernpu --lang en validate examples/tiny_mlp/spec.yaml

# Chinese output
eulernpu --lang zh validate examples/tiny_mlp/spec.yaml

# Japanese output
eulernpu --lang ja validate examples/tiny_mlp/spec.yaml

# Spanish output
eulernpu --lang es validate examples/tiny_mlp/spec.yaml

Common Option Conventions (eulerwa style)

Option	Description	Used in
`--lang`	Output language (ko/en/zh/ja/es)	all commands (root)
`--spec <path>`	YAML spec file path	compile, calibrate
`--artifact <path>`	Compiled `.npuart` artifact path	run, sim, profile, sweep, quantize, explain, generate, benchmark, replay, compress-cache
`--target <backend>`	Compilation backend (cpu_ref / npu_sim / zynq_ps / zynq_pl_stub)	compile, calibrate, board smoke
`--backend <backend>`	Execution backend	run, sim, profile, benchmark, replay
`--output / -o <path>`	Output file or directory	compile, calibrate, compress-cache
`--json-output`	Emit structured JSON to stdout	validate

All options use kebab-case (e.g. --json-output, --dump-graph, --compress-cache).

Top-Level Commands

`eulernpu --version`

Show version.

`eulernpu info [--dtypes] [--ops]`

Show NPU capability information.

Default: backends + capability matrix
--dtypes: show all supported dtype tiers with bit widths
--ops: show all 145 operators grouped by category (A–R)

`eulernpu validate <spec.yaml> [--json-output]`

Validate a spec YAML file against schema and semantic rules.

Exit 0: valid
Exit 1: errors found
--json-output: structured JSON output

`eulernpu compile --spec <spec.yaml> --target <backend> [--dump-graph] [--dump-plan] [-o <dir>]`

Compile a spec YAML into an executable artifact.

--target: backend name (cpu_ref, npu_sim, zynq_ps, zynq_pl_stub)
--dump-graph: save operator graph to file
--dump-plan: save execution/memory plan to file
-o: output directory (default: ./build/)

`eulernpu run --artifact <artifact> --backend <backend> [--input <data.npz>] [--golden <golden.npz>]`

Execute a compiled artifact on a backend.

--input: input data file (NumPy .npz)
--golden: golden reference for comparison
Prints execution summary: ops, time, peak memory

`eulernpu sim --artifact <artifact> --backend npu_sim [--trace <trace.json>] [--input <data.npz>]`

Run artifact on npu_sim with optional trace output.

npu_sim now traces all D-group Conv/Vision ops (conv1d/2d, depthwise, pointwise, pooling, global pool, upsample) and reports NPU clock-cycle estimates per op: estimated_cycles, estimated_latency_ms (at the spec's board.clock_mhz), and estimated_macs for compute ops. The trace JSON and the summary carry total_estimated_cycles / total_estimated_latency_ms.

`eulernpu profile --artifact <artifact> [--backend <backend>] [--all-boards]`

Profile execution: latency, peak memory, per-op cycle / latency / MAC breakdown (npu_sim), total estimated cycles and latency at clock_mhz.

--all-boards: compare estimated latency / LUT% / DSP% / power / feasibility across every board in constants.BOARD_PROFILES (xc7z020 / xczu3eg / xczu7ev / xck26 / xczu9eg — 5 boards) in one table, instead of the per-op breakdown.

`eulernpu sweep --artifact <artifact> [--systolic 8,16,32] [--output-format table|csv|json]`

Sweep the (board × systolic-size) design space and mark Pareto-optimal configurations (F6). For each board in BOARD_PROFILES (5 boards, now including the ADAS-class xczu7ev / xck26) and each systolic size, the spec's matmul_engine is reconfigured and an npu_sim trace produces latency / LUT% / DSP% / power; a point is Pareto-optimal if no other feasible point beats it on all three of (latency, power, DSP%). table is the default human-readable view; csv / json are machine-readable for downstream tools.

`eulernpu explain --artifact <artifact>`

Explain an artifact in human-readable form:

Graph structure (nodes, inputs, outputs)
Tensor dtypes
Memory plan (peak memory, buffer count)
Partition analysis (PL offload candidates, MACs, traffic)

`eulernpu calibrate --spec <spec.yaml> --dataset <npz> --target <backend> [--method minmax|percentile] [-o <output>]`

Calibrate quantization parameters from dataset. Outputs a calibration JSON consumed by quantize.

`eulernpu quantize --artifact <in.npuart> --calib-data <npz|dir> --out <out.npuart> [--weight-bits 4|8|16] [--activation-bits 8|16] [--scheme symmetric|asymmetric] [--method minmax|percentile] [--no-activations] [--report <json>]`

INT8-quantize a compiled artifact. Calibrates activation ranges from the calibration dataset (a .npz file or a directory of .npz files), quantizes weight matrices to int8 (inserting dequantize nodes) and fake-quantizes the graph's input activations (inserting quantize→dequantize). Produces a new artifact whose weight buffer is ~4× smaller. Use --no-activations for weight-only quantization. calibrate only emits a stats JSON; quantize produces a runnable INT8 artifact.

`eulernpu generate --artifact <lm.npuart> [--prompt-ids "1,2,3"] [--max-new-tokens N] [--stop-token N] [--sampler greedy|top_k] [--top-k K] [--temperature T] [--seed N] [--input <npz>] [--incremental]`

Autoregressively generate tokens from an LM-decoder artifact (project2 §5.2). Drives the decoder token-by-token (recompute over the growing prefix), sampling greedily or with seeded top-k. --prompt-ids are comma-separated token IDs; --input supplies extra conditioning inputs (e.g. a VLM's visual_kv). Used by the Edge VLM pipeline together with PipelineExecutor.

--incremental: when the graph has kv_cache_append nodes whose cache input is a graph input, keep the prior step's KV cache host-side and run only the new token each step (avoids O(N²) recompute). Falls back to full recompute when no such cache exists.

`eulernpu benchmark --artifact <artifact> --backend <backend> [--repeat N] [--warmup N]`

Benchmark inference latency. Reports mean, P50, P99, throughput.

`eulernpu replay --artifact <artifact> --stream <sensor_log.npz> [--mode streaming|batch] [--backend <backend>]`

Replay inference on a sensor log stream. Supports streaming and batch modes.

`eulernpu compress-cache --artifact <artifact> [--scheme int4|int3|fp8|auto] [-o <output>]`

Analyze cache compression potential. Reports per-tensor and total compression ratios.

`eulernpu board` Subcommands

`eulernpu board smoke --target <backend> [--emulated]`

Board smoke test for zynq_ps or zynq_pl_stub. Use --emulated to run the check on a host without a physical board attached.

# Emulated (no board required)
eulernpu board smoke --target zynq_ps --emulated
eulernpu board smoke --target zynq_pl_stub --emulated

`eulernpu demo` Subcommands (optional)

`eulernpu demo embodied-soc [--backend npu_sim|cpu_ref] [--seed N] [--speed S] [--no-color] [--realistic]`

Run the Embodied Multimodal AI SoC terminal demo (5-subsystem pipeline: live compile → parallel run → results → action trajectory → FPGA-readiness checklist). Requires rich (pip install eulernpu[demo]). --realistic uses deployable-scale model dimensions (slower). Source-checkout only — the demo lives under projects/.

Error Format Policy

Every CLI error follows the 3-line format (the eulerwa standard):

<Category>: <what went wrong>
Fix: <one-line actionable guidance>
See: <docs path>

The three parts are always present. Users rapidly learn to skip straight to the Fix: line once they know the category. The See: path points to the most relevant document for the error.

Message bodies (the text after : on the first line, and the text after Fix:) are translated. The labels Fix: and See: are intentionally untranslated so that scripts can parse them reliably regardless of the user's language.

i18n Notes

Translated:

--help / subcommand --help text
General log and completion messages (e.g. OK: spec is valid)
Error 3-line message bodies

Not translated (fixed across all languages):

Command names: info, validate, compile, run, sim, profile, sweep, explain, calibrate, quantize, generate, benchmark, replay, compress-cache, board smoke
Option names: --spec, --artifact, --target, --backend, --output, --json-output, --dump-graph, --dump-plan, --all-boards, --systolic, --incremental, --lang, ...
Backend names: cpu_ref, npu_sim, zynq_ps, zynq_pl_stub
Op / dtype names, JSON keys, spec keys, validator rule codes
Error format labels: Fix:, See:
Exit codes: 0 for success, 1 for failure

This split is intentional: humans need translations, but scripts grep for fixed tokens. Translating the command surface would break automation.

Examples

# Validate a spec
eulernpu validate examples/tiny_mlp/spec.yaml

# Compile for cpu_ref
eulernpu compile --spec examples/tiny_mlp/spec.yaml --target cpu_ref

# Run with golden comparison
eulernpu run --artifact build/tiny_mlp.npuart --backend cpu_ref \
    --golden examples/tiny_mlp/golden.npz

# Simulate with trace (conv ops + cycle estimates)
eulernpu sim --artifact build/tiny_mlp.npuart --backend npu_sim --trace trace.json

# INT8 quantization with calibration (Project 1 industrial KWS)
eulernpu compile --spec projects/industrial_kws/spec.yaml --target cpu_ref \
    -o projects/industrial_kws/build
eulernpu quantize --artifact projects/industrial_kws/build/industrial_kws.npuart \
    --calib-data projects/industrial_kws/data/calib \
    --out projects/industrial_kws/build/industrial_kws_int8.npuart \
    --report projects/industrial_kws/build/quant_report.json
eulernpu profile --artifact projects/industrial_kws/build/industrial_kws_int8.npuart \
    --backend npu_sim # → estimated_cycles / estimated_latency_ms ≤ 8ms @ 100MHz

# View dtypes and operators
eulernpu info --dtypes
eulernpu info --ops

# Explain an artifact
eulernpu explain --artifact build/tiny_mlp.npuart

# FPGA deployment (zynq_ps)
eulernpu compile --spec examples/tiny_mlp/spec.yaml --target zynq_ps
eulernpu run --artifact build/tiny_mlp.npuart --backend zynq_ps \
    --golden examples/tiny_mlp/golden.npz

# Board smoke test (emulated, no board required)
eulernpu board smoke --target zynq_ps --emulated
eulernpu board smoke --target zynq_pl_stub --emulated

# Language override
eulernpu --lang en validate examples/tiny_mlp/spec.yaml

EulerNPU CLI Reference

Entry Point

Global --lang Option

--lang ko|en|zh|ja|es

Common Option Conventions (eulerwa style)

Top-Level Commands

eulernpu --version

eulernpu info [--dtypes] [--ops]

eulernpu validate <spec.yaml> [--json-output]

eulernpu compile --spec <spec.yaml> --target <backend> [--dump-graph] [--dump-plan] [-o <dir>]

eulernpu run --artifact <artifact> --backend <backend> [--input <data.npz>] [--golden <golden.npz>]

eulernpu sim --artifact <artifact> --backend npu_sim [--trace <trace.json>] [--input <data.npz>]

eulernpu profile --artifact <artifact> [--backend <backend>] [--all-boards]

eulernpu sweep --artifact <artifact> [--systolic 8,16,32] [--output-format table|csv|json]

eulernpu explain --artifact <artifact>

eulernpu calibrate --spec <spec.yaml> --dataset <npz> --target <backend> [--method minmax|percentile] [-o <output>]

eulernpu quantize --artifact <in.npuart> --calib-data <npz|dir> --out <out.npuart> [--weight-bits 4|8|16] [--activation-bits 8|16] [--scheme symmetric|asymmetric] [--method minmax|percentile] [--no-activations] [--report <json>]

eulernpu generate --artifact <lm.npuart> [--prompt-ids "1,2,3"] [--max-new-tokens N] [--stop-token N] [--sampler greedy|top_k] [--top-k K] [--temperature T] [--seed N] [--input <npz>] [--incremental]

eulernpu benchmark --artifact <artifact> --backend <backend> [--repeat N] [--warmup N]

eulernpu replay --artifact <artifact> --stream <sensor_log.npz> [--mode streaming|batch] [--backend <backend>]

eulernpu compress-cache --artifact <artifact> [--scheme int4|int3|fp8|auto] [-o <output>]

eulernpu board Subcommands

eulernpu board smoke --target <backend> [--emulated]

eulernpu demo Subcommands (optional)

eulernpu demo embodied-soc [--backend npu_sim|cpu_ref] [--seed N] [--speed S] [--no-color] [--realistic]