EulerStack 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.md

Entry Point

eulerstack [--lang ko|en|zh|ja|es] [OPTIONS] COMMAND [ARGS]...

Root option:

Scope of i18n: - --help / subcommand --help — fully translated - General log and completion messages (e.g. OK: ... is valid.) - Error 3-line format — message body is translated; the Fix: / See: labels stay fixed across languages

Out of i18n scope (fixed): - Command names: validate, explain, compile, schema, presets - Option names: --preset, --output, --output-dir, --report, --validate-only, --print-config, --dry-run, --lang - 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.

Common Option Conventions (eulerwa style)

All options use kebab-case (e.g. --validate-only, --print-config).

Language Examples

# Korean (default)
eulerstack validate --preset my_model.yml

# English
eulerstack --lang en validate --preset my_model.yml

# Chinese / Japanese / Spanish
eulerstack --lang zh explain --preset my_model.yml
eulerstack --lang ja explain --preset my_model.yml
eulerstack --lang es explain --preset my_model.yml

# Via environment variable
EULERSTACK_LANG=en eulerstack validate --preset my_model.yml

Resolution precedence: --lang flag > EULERSTACK_LANG env var > default (ko).

Top-Level Commands

eulerstack validate

Validate a YAML spec file against the schema.

# Basic validation
eulerstack validate --preset my_model.yml

# Full report with realism checks and parameter estimate
eulerstack validate --preset my_model.yml --report

# Explicit validate-only (for consistency with eulerwa CLI family)
eulerstack validate --preset my_model.yml --validate-only

• Exit 0: valid (no schema errors)
• Exit 1: one or more validation errors, printed in 3-line format

What --report includes: - Schema validation status (OK / FAIL) - Estimated parameter count and comparison against target_params - Total layer count with mixer-type breakdown - Realism warnings (head_dim range, MoE ratio, seq_len/d_model ratio, etc.) - INFO-level layer-composition summary

The --report form is the recommended way to confirm a spec does what you think it does, before spending GPU time on it.

eulerstack explain

Print a human-readable summary of a YAML spec.

eulerstack explain --preset configs/presets/llm_2b_simple.yml

Output includes: - Model identity (name, family hint, dimensions, dtype) - Layer templates (mixer, ffn, norm, residual) - Layer schedule (template × repeat) - Estimated parameter count and ratio against target_params

explain runs without GPU and produces stable, deterministic output for the same YAML, so it is safe to paste into code reviews and design documents.

eulerstack compile

Compile YAML spec → IR → either a JSON runtime config or a HuggingFace model directory.

# Write JSON runtime config to file
eulerstack compile --preset my_model.yml --output compiled.json

# Build and save an HF model directory (config.json + model.safetensors)
eulerstack compile --preset my_model.yml --output-dir ./my_model

# Print the config to stdout
eulerstack compile --preset my_model.yml --print-config

# Dry run (alias for --print-config)
eulerstack compile --preset my_model.yml --dry-run

# Validate only, do not compile
eulerstack compile --preset my_model.yml --validate-only

--output-dir creates an HF-compatible model directory that loads with:

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("./my_model", trust_remote_code=True)

The directory contains config.json, model.safetensors (random weights), plus configuration_eulerstack.py and modeling_eulerstack.py so that trust_remote_code=True works on machines without EulerStack installed. This is the primary way to produce a training-ready model for eulerforge or any HF-compatible trainer.

eulerstack schema

Print a summary of the YAML schema.

eulerstack schema

The output lists top-level keys, the enum values for each .type field, and the compile targets supported. Useful as a quick reference; the authoritative schema reference lives in tutorials/en/03_spec_reference.md.

eulerstack presets Subcommands

eulerstack presets list

List all available presets with parameter estimates.

eulerstack presets list

Output is a table: preset name, layer count, estimated parameters, target parameters, and ratio. Useful as the first command to run after installation.

eulerstack presets show <name>

Print detailed information about a single preset.

eulerstack presets show llm_2b_simple

The output is equivalent to running eulerstack explain --preset <path> against the preset's YAML file, plus the preset name header.

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>

Error categories:

• ValidationError — schema / structure violations (unknown key, missing field, bad enum, negative dropout, …)
• CompatibilityError — cross-field incompatibilities (e.g. mamba + kv_cache=true)
• CompileError — compilation failures
• NormalizationError — IR normalization failures

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, usually under docs/architectures/ or docs/tutorials/.

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.

Comparison with eulerforge (eulerwa CLI family)

The EulerStack CLI intentionally mirrors the eulerforge CLI conventions so that users moving between the two tools see the same patterns.

When adding a new option, use an existing eulerforge name if one applies. New option names should follow kebab-case and be short enough to type without shell completion.

See Also

• tutorials/en/01_validate_a_spec.md — how validation layers work
• tutorials/en/03_spec_reference.md — full YAML field reference
• tutorials/en/04_compile_and_explain.md — the compile and explain commands in practice
• tutorials/quickstart.md — 30-second CLI tour