Docs / CLI

CLI quickstart

One command, no account, no GPU. It reads a model's config.json from Hugging Face (or a graph file you have) and answers before the job takes a card or a launch takes traffic.

Node 18 or newer. The current release is neurarch 0.3.0; npx neurarch@0.3.0 pins it. The outputs below were captured with 0.2.0 on 2026-10-18; they are cut, never reworded. What it sends over the network: trust page.

What a job needs
Does the data fit
Parallel layout
Serving launch
Read an OOM
Past jobs
Exit codes
New in 0.3.0

What a training job needs

$ npx neurarch Qwen/Qwen3-8B --batch 8

Qwen/Qwen3-8B  qwen3 · text-generation

  published (safetensors.total)  8.19B  8,190,735,360
  derived (config.json alone)   8.19B  8,190,878,080
  difference                    +0.00%  within 2%: the reconstruction matches the checkpoint
  ...
  training memory (no price without --data)
    fits            T4 no  A100_40 no  H100_80 no  (training peak ~259.1 GB at batch 8, 2048 tokens, 1.15x headroom)
    upper bound     370.5 GB (the estimate x 1.43: held out by architecture, 95% of 91 measured runs peaked at or under it)

The first lines compare the parameter count derived from the config with the count the checkpoint stores, so you can see whether the reading is worth trusting before you read the rest. Useful flags:

Flag	Does
`--batch N --seq-len N`	The training peak at that batch and sequence length (default 2048 tokens, or the context if shorter).
`--data 3M --gpu a100-80gb`	What one run costs, for a training set of that size, on that card. No `--data`, no price.
`--lora r=16,targets=q_proj,v_proj`	Size a LoRA run instead of a full fine-tune.
`--inference --batch 4 --seq-len 4096 --gen 512`	Weights plus KV cache for a generation job, and which cards hold it.
`--json`, `--layers`	Machine-readable output; every layer instead of the first 12.

Every number is derived from the config, not measured; the memory model's measured runs are public at /memory-calibration.

Does your data fit what the config accepts

$ npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524

  data fit checked: sequence length, tokenizer size
    block Sequences of 1024 tokens are longer than the 512-row position table
          fix: Truncate or chunk to 512 tokens, or pick a model whose context covers 1024.
    block The tokenizer has 30524 ids and the embedding has 30522 rows
          fix: Call model.resize_token_embeddings(len(tokenizer)) before training, and budget for the new rows.

Also --classes N (labels against the head) and --image-size N --channels N (against the first layer). These are the jobs that crash on the first batch, after the reservation; this exits 1 before it.

Is this parallel split legal and balanced

$ npx neurarch layout Qwen/Qwen3-8B --tp 4 --pp 4 --dp 8 --global-batch 512 --seq-len 4096

  Balance: slowest stage 3 at 1.24x the mean stage's predicted time.
  Rebalanced split 10,10,10,6: 1.02x, predicted 20.0% faster per step at 64 microbatches (2579 ms); 21.2% as microbatches grow.
  ...
  checked: tp-heads, tp-kv-heads, tp-hidden, tp-ffn, tp-node, cp-seq, batch-arithmetic, pp-over-blocks, stage-balance, pipeline-bubble, stage-memory

Legality (TP against heads, KV heads, hidden and FFN sizes; PP against blocks; the batch arithmetic) is exact. Stage times are predicted, and the output says so. A local graph file works too (npx neurarch layout ./graph.json ...) and makes no network request. npx neurarch layout --help lists every flag.

Will this serving launch start

Put the launch command after --, exactly as you would run it. vLLM, SGLang and llama.cpp are read.

$ npx neurarch serve-check Qwen/Qwen3-8B --gpu l4 --gpus 4 -- vllm serve Qwen/Qwen3-8B -tp 4 --max-model-len 32768

  Qwen/Qwen3-8B on vLLM
  TP 4 x PP 1 x DP 1, 4 x l4 (sm89), dtype bf16, weights unquantized, KV cache auto
  served length 32768 (--max-model-len 32768); the model's derived maximum 40960

  memory per GPU   budget 21.6 GB, weights 4.10 GB, KV room 17.50 GB
  ...
  info  The template has a thinking block and no --reasoning-parser is set
        fix: Add --reasoning-parser qwen3.

Why a job ran out of memory

$ npx neurarch oom error.txt --model FacebookAI/xlm-roberta-large --batch 1 --seq-len 128

cause    too-big-for-card

The job is bigger than this card: the predicted peak is 10.8 GB (12.5 GB with headroom) on a 4.29 GB card.

error.txt is the text PyTorch printed with torch.OutOfMemoryError; pipe it in with python train.py 2>&1 | npx neurarch oom - --model .... Fixes come least invasive first.

Requested against needed, over past jobs

$ npx neurarch rightsize jobs.csv

One row per job: the model, what it requested, batch and hours. The package ships a sample at examples/jobs.sample.csv; npx neurarch rightsize --help documents the columns. On that sample it prints "6 jobs, 174 GPU-hours, $507.85 spent; $328.53 of that was reserved capacity no job needed", with a row per job naming the smallest card that holds it. That figure is capacity reserved and not needed, not money saved.

Exit codes and scripting

Exit 1 when the model cannot be read or a check blocks, 0 otherwise, so it composes in CI and shell scripts. Set HF_TOKEN to read a gated repo; it is sent to huggingface.co only.

New in 0.3.0

On npm since 2026-10-18: npx neurarch has them, and npx neurarch@0.3.0 pins the release.

neurarch pin-check [paths]: Hugging Face downloads not pinned to a commit, following Bandit's B615, with --sarif for code scanning.
.neurarch.yml policy: severities, budget lines, waivers with an owner and an expiry, a baseline, SARIF output.
--attest and --cyclonedx: a deterministic, signable pre-check record. See trust; the neurarch:* properties --cyclonedx writes are listed at CycloneDX properties.

Next: put the same check where jobs are submitted, in the admission hooks.