CLI reference

This section describes all the np commands available in Arm AI Model Optimizer.

Command summary

Auth and environment

Command	Description
`np health ready`	Check backend connectivity
`np auth login`, `logout`, `status`	Log in, log out, or check authentication (required before every other command)
`np workspace init`	Initialize workspace

Resource management

Command	Description
`np projects create` / `ls` / `info`	Create, list, or inspect projects (`--copy-config` is supported)
`np models ls`, `register`	List preset models or register a model (see model_register.yaml)
`np datasets ls`, `register`	List or register datasets
`np devices ls`	List supported device, runtime, and backend combinations
`np experiments create`, `detail`, `ls`, `info`	Create, detail, list, or inspect experiments (`--copy-config` is supported)
`np jobs ls`, `info`	List or inspect jobs within an experiment

Execution

Command	Description
`np validate`	Validate configuration before running
`np run`	Execute the optimization pipeline (`--wait`, `--retry`, `--dry-run`)
`np cancel`	Cancel an experiment and any in-progress post-hoc measurements (the only way to stop something on the backend)

Viewing results

Command	Description
`np status`	Check run status
`np report`	View the results report
`np export`	Export artifacts
`np evaluate`	Post-hoc accuracy evaluation
`np profile`	Measure latency and memory (`--method mlia`)
`np analyze sensitivity`	Module-wise sensitivity lookup, recomputes on demand (expert option)
`np visualize` / `auth`	Generate a visualization link or bootstrap browser session access
`np ls --post-hoc`	List the post-hoc run history

Global options

Option	Short	Description
`--version`	`-V`	Show CLI version
`--install-completion`	-	Install shell tab completion
`--show-completion`	-	Show completion script

`np health ready`

Checks that the backend API is reachable, independent of authentication. Useful as a first sanity check before np auth login.

np health ready

Sample output

[ERROR] [CLI] Environment variable NP_CLIENT_API_URL (or NP_ENTERPRISE_API_URL) is not set.

This is the error you get if you do not set the required environment variable. See Quick start. A reachable backend prints a plain success message and exits 0.

`np auth`

Stores, verifies, and clears your login credential locally. Every np command, including np workspace init, checks this before running.

To obtain a token or replace an expired or lost one, see Manage access tokens.

Subcommand	Argument	Description
`login`	`<credential>` (required)	Stores the token generated from the AI Portal locally
`logout`	-	Removes the stored credential
`status`	-	Shows current login state and expiry (checked locally, no server call)

np auth login <credential>
np auth status
np auth logout

Sample output

$ np auth login eyJhbGciOi...
✔ Logged in.
  Access token valid until: 2026-07-29T14:32:00Z

$ np auth status
============================================================
Authentication
============================================================

[ Result Summary ]
 Auth server      https://auth.your-deployment.netspresso.ai
 User             <your-username>
 Tenant           <your-tenant>
 Access token     valid
 Access expires   2026-07-29T14:32:00+00:00
 Refresh expires  2027-07-26T11:41:46+00:00

Your session refreshes automatically in the background when the access token expires. You do not need to log in again unless the refresh fails. The credential is stored at ~/.config/np/auth.json; np auth logout removes it.

Situation	Message
No credential stored	`Not authenticated. Run 'np auth login <credential>' first.`
Token invalid	`Access token invalid. Run 'np auth login <credential>' again.`
Refresh failed	`Token refresh failed: <reason>. Run 'np auth login <credential>' again.`
Auth server unreachable	`Failed to reach auth server. Check network or try again later.`

`np workspace init`

Initializes a new workspace directory. Run once for each working environment.

np workspace init

Sample output

2026-08-20 13:12.00 [INFO ] [CLI] Initializing New Workspace
2026-08-20 13:12.00 [INFO ] [CLI] Checking directory availability...
2026-08-20 13:12.00 [INFO ] [CLI] Created workspace root: <cwd>/workspace

============================================================
[Phase 1] Sample Project Setup
============================================================
2026-08-20 13:12.00 [INFO ] [CLI] Generating sample project...

============================================================
Summary
============================================================
2026-08-20 13:12.02 [INFO ] [CLI] Workspace initialized successfully.

[ Result Summary ]
 Workspace Path     <cwd>/workspace
 Sample Experiment  <cwd>/workspace/sample_project/experiment_00
 Model              resnet18_pt2_pytorch_static_fp32
 Calibration        sample_image_calib_seed42_n2
 Evaluation         sample_image_eval_seed42_n2

note

Run once for each machine. The workspace root is stored globally in ~/.config/np/config.json, not per-directory. Running this command again from anywhere reports the existing path rather than creating a second workspace. Delete ~/.config/np/config.json first if you actually want to move it. The workspace contains all your projects and shared datasets, and comes with a ready-to-run sample project.

`np projects create`

Creates a project that binds a model to a target device.

np projects create \
    --name <name> --model <model-name> --device <device> \
    --runtime <runtime> --backend <backend> \
    --calibration-dataset <dataset-name> --evaluation-dataset <dataset-name>

np projects create --copy-config <name|ref_id>   # copy an existing project's config

Example: CV model

np projects create \
    --name resnet-rpi5 \
    --model resnet50 \
    --device raspberry_pi_5_16gb \
    --runtime executorch \
    --backend xnnpack

Example: Hugging Face LLM

np projects create \
    --name smollm2-m4 \
    --model smollm2_hf \
    --device m4_macbook \
    --runtime executorch \
    --backend xnnpack \
    --calibration-dataset c4_calib_seed42_n30_shuf \
    --evaluation-dataset c4_eval_seed42_n30_shuf \
    --gpu-device cuda:1

Option	Required	Description
`--name`, `-n`	No	Project name (3–50 characters, alphanumeric, hyphens and underscores allowed)
`--model`, `-m`	Yes	Model name (exact match). Run `np models ls` to see available models.
`--device`, `-d`	Yes	Target device (for example `raspberry_pi_5_16gb`)
`--runtime`, `-r`	Yes	Inference runtime (for example `executorch`)
`--backend`, `-b`	Yes	Runtime backend (for example `xnnpack`)
`--calibration-dataset`, `-C`	No	Calibration dataset name (preset or custom). Run `np datasets ls` to see available datasets.
`--evaluation-dataset`, `-E`	No	Evaluation dataset name (preset or custom). Run `np datasets ls` to see available datasets.
`--gpu-device`	No	GPU device for execution, for example `cpu`, `cuda:0` (the default), `cuda:1`
`--copy-config`	No	Copy model, dataset, device, runtime, backend, and GPU settings from an existing project, with overrides for each option. If the resulting combination is invalid, the backend rejects it at creation time.

Run from inside the workspace/ directory. You can omit all options to enter interactive mode.

np projects ls and np projects info <ref_id> list and inspect projects (see Listing and inspecting resources for shared options).

`np models ls`

Lists available preset models from the server.

np models ls
np models ls --filter domain=CV
np models ls --filter domain=LLM --sort name

Option	Description
`--sort`, `-s`	Sort by field: `domain`, `format`, `framework`, `name`, `source`, `task`, `type`. Append `:asc` (the default) or `:desc` for direction. Repeatable for multilevel sort (for example `--sort domain --sort name:desc`)
`--filter`, `-f`	Filter by `key=value` (repeatable, partial match). Keys: `domain`, `framework`, `name`, `type`

Sample output

2026-08-21 13:30.25 [INFO ] [CLI] Listing Models
                                                      Models (51)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ Name                                        ┃ Type   ┃ Domain ┃ Task             ┃ Source      ┃ Format ┃ Framework ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ conformer_ctc_hf_pytorch                    │ PRESET │ AUDIO  │ Speech To Text   │ HUGGINGFACE │ HF     │ PYTORCH   │
│ resnet50_pt2_pytorch_static_fp32            │ PRESET │ CV     │ Classification   │ TORCHVISION │ PT2    │ PYTORCH   │
│ detr_resnet_50_pt2_pytorch_static_fp32      │ PRESET │ CV     │ Object Detection │ HUGGINGFACE │ PT2    │ PYTORCH   │
│ smollm2_hf_pytorch                          │ PRESET │ LLM    │ Text Generation  │ HUGGINGFACE │ HF     │ HUGGINGFACE │
│ ...                                         │ ...    │ ...    │ ...              │ ...         │ ...    │ ...       │
└─────────────────────────────────────────────┴────────┴────────┴──────────────────┴─────────────┴────────┴───────────┘

[ Next Steps ]
Create a project with a model:
  $ np projects create --model <name>

See Supported models and devices for the full catalog.

`np models register`

Registers a Hugging Face model by repository ID. See Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD) formats for the model list, the Status lifecycle, and reregistration behavior.

np models register                                  # looks for ./model_register.yaml
np models register ./recipes/qwen.yaml               # or an explicit path (any filename)
np models register model_register.yaml --wait        # block until GE verification finishes
np models register model_register.yaml --force-update   # re-register a changed source revision

Option	Required	Description
`path` (positional)	No	Recipe file path: see `model_register.yaml`. Defaults to `model_register.yaml` in the current directory if omitted. The local filename does not matter otherwise.
`--wait`	No	Block until Graph Extractor verification completes, instead of returning right after upload. Without it, check `np models ls` for `Status: Usable` before using the model.
`--force-update`	No	Registers a new source revision of an already-registered model. The previous version is retired from listings, not overwritten in place.

A registered model is not usable until its Status in np models ls reads Usable. Uploading means Graph Extractor verification is still pending or running, and Failed (often from a recipe missing pipeline) means it needs to be fixed and reregistered. See Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD) formats for the full lifecycle and error examples.

Sample output

$ np models register model_register.yaml --wait
2026-08-22 13:05.00 [INFO ] [CLI] Registering Model
2026-08-22 13:05.00 [INFO ] [CLI] Reading model metadata from the Hugging Face Hub...
2026-08-22 13:05.01 [INFO ] [CLI] Registering the model on the server...
2026-08-22 13:05.02 [INFO ] [CLI] Uploading model_register.yaml to the server...
2026-08-22 13:05.02 [INFO ] [CLI] Validating model_register.yaml on the server...
2026-08-22 13:05.03 [INFO ] [CLI] Downloading model weights from the Hugging Face Hub (several GB — this can take a while)...
2026-08-22 13:06.30 [INFO ] [CLI] Bundling the weights into a single tar archive...
2026-08-22 13:06.42 [INFO ] [CLI] Bundled the weights into a tar archive (953.3 MiB).
2026-08-22 13:06.42 [INFO ] [CLI] Uploading the weights to the server...
2026-08-22 13:07.20 [INFO ] [CLI] Uploading weights... 79% (754.7 MiB / 953.3 MiB)
2026-08-22 13:07.38 [INFO ] [CLI] Confirming the upload with the server...

============================================================
Summary
============================================================
2026-08-22 13:07.40 [DONE ] [CLI] Model registered and verified successfully.

[ Next Steps ]
Create a project with this model:
  $ np projects create --model <name>

`model_register.yaml`

The recipe file passed as the path argument above. model is a Hugging Face repository ID. The registered model's name is derived from it, so there is no separate name field.

model_register.yaml
model: Qwen/Qwen2.5-0.5B-Instruct   # HF repo id
domain: LLM
task: TEXT_GENERATION
pipeline: generate                  # Graph Extractor trace entry function (HF only)
inputs:                             # HF only, required
  input_ids:
    dtype: int64
    dims: {0: 1, 1: 128}

Field	Required	Description	Accepted values
`model`	Yes	Hugging Face repository ID (must match a model list entry); also the source of the derived model name	-
`domain`	Yes	Model domain	`LLM` (fixed in this release)
`task`	Yes	Task type	`TEXT_GENERATION` (fixed in this release)
`pipeline`	Yes (HF only)	Graph Extractor trace entry function	`generate` (fixed in this release)
`inputs`	Yes (HF only)	Input tensors, keyed by name, each with a dtype and per-dimension size. This is what Graph Extractor traces against to fix every shape as static	for example `input_ids: {dtype: int64, dims: {0: 1, 1: 128}}`

1 recipe registers exactly 1 model card. domain, task, and pipeline exist as schema fields but no combination other than the one shown above is supported yet. inputs is the only place shape is declared anywhere in the system. There is no separate shape configuration in run.yaml or run.detail.yaml.

`np datasets ls`

Lists all datasets registered in the workspace.

np datasets ls
np datasets ls --filter type=PRESET
np datasets ls --sort name

Option	Description
`--sort`, `-s`	Sort by field: `name`, `raw-data`, `samples`, `seed`, `shuffle`, `split`, `strategy`, `task`, `type`. Append `:asc` or `:desc` for direction. Repeatable for multi-level sort.
`--filter`, `-f`	Filter by `key=value`. Keys: `name`, `raw-data`, `split`, `type`.

Sample output

$ np datasets ls
2026-08-20 13:47.18 [INFO ] [CLI] Listing Datasets
                                          Datasets (58)
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Name                 ┃ Type   ┃ Task             ┃ Split       ┃ Raw Data   ┃ Samples ┃ Seed ┃ Strategy   ┃ Shuffle ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ imagenet1k_calib_se… │ PRESET │ Classification   │ CALIBRATION │ imagenet1k │    1000 │   42 │ STRATIFIED │ False   │ Usable │
│ coco2017_calib_seed… │ PRESET │ Object Detection │ CALIBRATION │ coco2017   │     200 │   42 │ RANDOM     │ True    │ Usable │
│ doc-capture-calib-30 │ CUSTOM │ Text Generation  │ CALIBRATION │ plain_text │      30 │    0 │ FULL       │ False   │ Usable │
│ ...                  │ ...    │ ...              │ ...         │ ...        │     ... │  ... │ ...        │ ...     │ ...    │
└──────────────────────┴────────┴──────────────────┴─────────────┴────────────┴─────────┴──────┴────────────┴─────────┴────────┘

CUSTOM rows read Seed 0 / Strategy FULL / Shuffle False: you sampled the data yourself, so the server takes the folder as given rather than drawing a sample from it. Strategy for PRESET rows varies (RANDOM, STRATIFIED, ...) by dataset, not always RANDOM.

`np datasets register`

Registers your own calibration or evaluation data (BYOD). Runs synchronously: it uploads, validates, and reports success or failure in the same call, with no job to poll for. See Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD) formats.

np datasets register --source <dir> (--calibration|--evaluation) \
  --task <TASK> --raw-data <format> [--name <name>]

Option	Required	Description
`--source`	Yes	Path to your already-sampled data folder
`--calibration`, `--evaluation`	Yes	Purpose (mutually exclusive). For object detection, instance, or semantic segmentation, `--calibration` is checked more leniently (images only) than `--evaluation` (needs matching ground truth)
`--task`	Yes	Task type, `UPPER_SNAKE_CASE` (for example `TEXT_GENERATION`, `OBJECT_DETECTION`)
`--raw-data`	Yes	Which of the supported folder formats you are using (see Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD) formats); checked against `--task` for compatibility before anything uploads.
`--name`	No	Dataset name; auto-generated if omitted

Sampling-related options (seed, strategy, shuffling) are not accepted, because Arm AI Model Optimizer is not doing the sampling. Bring data you have already sampled. --raw-data is validated in 2 stages: an instant rejection before upload if the format name is unknown or incompatible with --task, and a dry-run structural check right after upload if the folder itself does not match what the format expects (engine code NP-SDV-422). Reregistering identical data with identical options is deduplicated by content fingerprint rather than creating a second copy.

Sample output: success

$ np datasets register --source ./my_corpus_calib_30 --calibration --task TEXT_GENERATION --raw-data plain_text --name doc-capture-calib-30
[INFO ] [CLI] Registering Dataset
[INFO ] [CLI] Checking the request with the server and requesting an upload URL...
[INFO ] [CLI] Archiving the folder into a single tar (this can take a while for a large dataset)...
[INFO ] [CLI] Computing the SHA-256 of the archive...
[INFO ] [CLI] Uploading the archive to the server...
[INFO ] [CLI] Registering and validating on the server. Validation reads every sample once per task, so this can take several minutes - do not interrupt it.

============================================================
Summary
============================================================
[DONE ] [CLI] Dataset registered successfully.

[ Result Summary ]
 Sample    doc-capture-calib-30
 Ref ID    5e6f7081-9203-4c4d-9e5f-60718293a4b5
 Split     CALIBRATION
 Tasks     Text Generation
 Uploaded  70.0 KiB
 Status    CREATED

[ Next Steps ]
Create a project with this dataset:
  $ np projects create --calibration-dataset doc-capture-calib-30

Sample output: rejected

============================================================
Registration rejected
============================================================

[ Task results ]
 Text Generation  REJECT   TEXT_GENERATION: Filtered dataset rows are less than
                  config num_samples | hints: every structural entry of the
                  declared raw-data format 'plain_text' is present — the
                  failure may be at the file content/format level

[ Validation details ]
 Samples counted by the server  5
 Engine code                    NP-SDV-422
 Sample ref ID                  7b6fc8bf-72d8-44f5-9370-fe2b1aba3aff

[ Next Steps ]
Fix the folder for the rejected tasks above, then register again:
  $ np datasets register --source my_corpus_calib_5 --calibration --task TEXT_GENERATION --raw-data plain_text --name doc-capture-calib

The archive still uploads even when registration is rejected, but the sample itself is not usable until validation passes. Fix the folder and run the same command again. Reregistering an unchanged archive is idempotent, so it is not re-uploaded.

See Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD) formats for the exact folder layout, file contents, and registration command for each --task and --raw-data combination.

`np devices ls`

Lists supported device, runtime, and backend combinations.

np devices ls
np devices ls --filter device=raspberry
np devices ls --filter backend=xnnpack

Option	Description
`--sort`, `-s`	Sort by field: `device`, `runtime`, `backend`
`--filter`, `-f`	Filter by `key=value`. Keys: `device`, `runtime`, `backend`

Sample output

      Supported Device Combinations
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Device              ┃ Runtime    ┃ Backend ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ alif_e8_devkit      │ executorch │ ethos_u │
│ m4_macbook          │ executorch │ xnnpack │
│ raspberry_pi_5_16gb │ executorch │ xnnpack │
│ graviton4           │ executorch │ xnnpack │
│ vivo_x300_pro       │ executorch │ xnnpack │
└─────────────────────┴────────────┴─────────┘

See Supported models and Supported devices for the full matrix.

`np experiments create` and `np experiments detail`

Creates an experiment and generates a run.yaml with a pipeline preset.

np experiments create --steps go,gq
np experiments create --copy-config <name|ref_id>             # copy verbatim
np experiments create --copy-config <name|ref_id> --steps aq,go,gq  # regenerate, overlay matching tuning

np experiments detail   # generate run.detail.yaml

Option	Required	Description
`--steps`, `-s`	No	Pipeline steps. Default: `go,gq`.
`--name`, `-n`	No	Experiment name. Auto-generated if omitted (`experiment_00`, `experiment_01`, ...).
`--input-job`	No	Input job ID to derive from (creates derivation experiment using specified job's output)
`--copy-config`	No	Copy an existing project or experiment configuration within the same project

Supported step values

Value	Full name
`aq`	Advanced Quantize
`go`	Graph Optimize
`gq`	Graph Quantize

--copy-config without --steps copies run.yaml word for word, as well as run.detail.yaml, if present. With --steps, it regenerates a structurally correct run.yaml for the new step set, then overlays matching tuning values by name. Anything that does not carry over is dropped with a warning.

Experiments are automatically named experiment_00, experiment_01, and so on. Run from inside the project directory.

Sample output

$ np experiments create --steps aq,go,gq
2026-08-21 14:50.18 [INFO ] [CLI] Creating Experiment
2026-08-21 14:50.18 [DONE ] [CLI] Generated: run.yaml

[ Result Summary ]
 Experiment  experiment_00
 Location    /path/to/workspace/my-project/experiment_00

[ Next Steps ]
Go to experiment folder and review configuration:
  $ cd experiment_00
  $ vi run.yaml
  $ np validate

np experiments detail generates a run.detail.yaml template based on the current run.yaml. Run from inside the experiment directory that contains a run.yaml. See run.detail.yaml for the full reference.

Sample output

$ np experiments detail
2026-08-21 15:40.05 [INFO ] [CLI] Generating Detail Configuration
2026-08-21 15:40.05 [DONE ] [CLI] Generated: run.detail.yaml

[ Next Steps ]
Edit the detailed configuration:
  $ vi run.detail.yaml

np experiments ls and np experiments info <ref_id> list and inspect experiments within a project.

`np jobs ls`

Lists the jobs within an experiment.

np jobs ls
np jobs ls --experiment <experiment_id|name>
np jobs ls --filter step-type=graph_quantization
np jobs ls --sort started:desc

Option	Required	Description
`--experiment`, `-e`	No	Experiment ref_id or name. Auto-detected from current working directory if omitted.
`--filter`, `-f`	No	`<col>=<pattern>`, partial match. Columns: `name`, `step-type`, `status`.
`--sort`, `-s`	No	`<col>[:asc\|:desc]`, repeatable. Columns: `name`, `step-index`, `started`, `status`. Default: `step-index:asc`.
`--json`, `--plain`	No	Machine-readable output

Sample output

$ np jobs ls
                                                           Jobs (2)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ ID                                   ┃ Name              ┃ Step Index ┃ Step Type          ┃ Status  ┃ Started             ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ 2b3c4d5e-6f70-4819-a2b3-c4d5e6f70819 │ 01_graph_optimize │          0 │ graph_optimization │ success │ 2026-08-20 17:05:10 │
│ 3c4d5e6f-7081-4a2b-9c3d-4e5f60718293 │ 02_graph_quantize │          1 │ graph_quantization │ success │ 2026-08-20 17:06:57 │
└──────────────────────────────────────┴───────────────────┴────────────┴────────────────────┴─────────┴─────────────────────┘

Why np jobs ls has no metric columns

A listing view has no comparison baseline. This means that a Graph Optimizer job with a signal-to-noise (SNR) reading numerically higher than the reading for a Graph Quantizer job could misleadingly look like GO is better when the difference is just a property of the step type. That comparison role stays with np report. np jobs info keeps its own metrics table, useful when you already know a job ID and want its results directly, without scanning through np report's per-execution tables.

`np jobs info`

Shows full detail for a single job, including a metrics table. This is also the only way to see metrics for a post-hoc (evaluate or profile) job, because np report does not cover post-hoc results and np ls --post-hoc does not carry metric values.

np jobs info <job_id>

Option	Required	Description
`job_id` (positional)	Yes	Job ref_id (UUID, full form), taken from the `np jobs ls` `ID` column. Name resolution is not supported in this case, because job names are only unique within an experiment
`--json`, `--plain`	No	Machine-readable output

Sample output

$ np jobs info <job_id>

   Name              02_graph_quantize
   ID                f1a2b3c4-5d6e-4f70-8912-a3b4c5d6e7f8
   Experiment ID     4d5e6f70-8192-4b3c-8d4e-5f6071829314
   Step Type         graph_quantization
   Step Index        1

   Status            success
   Created           2026-08-22 14:10:00
   Started           2026-08-22 14:12:11
   Ended             2026-08-22 14:19:14
   Duration          7m 3s

   Input Job ID      -

   Model Ref ID      9c8b7a6f-5e4d-4321-9f8e-7d6c5b4a3210

   Metrics (3)
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric ┃ Value                ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ SNR    │ -5.612707138061523   │
│ MACS   │ 56510400.0           │
│ PARAMS │ 2558736.0            │
└────────┴──────────────────────┘

A graph_quantize job always reports SNR alongside MACs and params.

For some LLM jobs, the Metrics table shows more than 1 row for the same metric name (for example 2 SNR rows) rather than a single averaged value. This release does not label which internal graph each row belongs to.

A failed job adds an Error row with the failure message.

Listing and inspecting resources

There are 6 read commands, arranged in 3 ls and info pairs: np projects ls and np projects info, np experiments ls and np experiments info, and np jobs ls and np jobs info. The ls commands list resources and their ref_id values. The info <ref_id> commands show details about a specific resource. Use np status to track progress and np report to compare results.

The following shared ls options are available:

--filter/-f <col>=<pattern>
--sort/-s <col>[:asc|:desc]
--json
--plain (tab-separated values)

There is no --limit or page-size flag. Use --json and page on the client side if you need to. info commands support --json or --plain only.

`np validate`

Checks run.yaml (and optionally run.detail.yaml) for configuration errors before running the pipeline.

np validate
np validate --config run.yaml,run.detail.yaml

Option	Required	Description
`--experiment`, `-e`	No	Target experiment by ref_id instead of the current directory
`--config`, `-c`	No	Comma-separated YAML path(s) to validate instead of the experiment directory's files (for example `run.yaml,run.detail.yaml`). Experiment context (current working directory or `--experiment`) is still required

Sample output: pass

$ np validate
2026-08-20 18:20.00 [INFO ] [CLI] Validating run configuration
2026-08-20 18:20.02 [DONE ] [CLI] Validation Passed. No issues found.
╭─────────────────────────────── Execution Plan ───────────────────────────────╮
│ Steps:                                                                       │
│   [1/2] graph_optimize                                                       │
│   [2/2] graph_quantize — scheme: W8-A8                                       │
│ Profile: INPUT_MODEL, GRAPH_OPTIMIZE, OUTPUT_MODEL                           │
│ Evaluate:                                                                    │
│   INPUT_MODEL (snr)                                                          │
│   GRAPH_OPTIMIZE (snr)                                                       │
│   OUTPUT_MODEL (snr)                                                         │
│ Total: 8 jobs                                                                │
╰──────────────────────────────────────────────────────────────────────────────╯

`np run`

Submits the pipeline defined in run.yaml to the Backend, where it executes asynchronously on a GPU worker.

np run --wait                    # submit and follow progress
np run --retry                   # resume a failed/cancelled run — skips successful steps
np run --dry-run                 # preview pipeline steps without executing

Option	Required	Description
`--experiment`, `-e`	No	Experiment ref_id to run
`--wait`	No	Follow progress in the terminal instead of returning immediately after submission
`--retry`	No	Resume a failed run, skipping already-completed steps
`--dry-run`	No	Preview the execution plan without running any optimization

Without --wait, the command returns immediately after submission. Run from inside the experiment directory.

Ctrl+C only detaches

Pressing Ctrl+C while np run --wait is polling stops the CLI from watching, but does not cancel anything. The pipeline keeps executing on the backend. To stop it, run np cancel in another terminal, or after the fact.

Sample output: Ctrl+C

$ np run --wait
...
^C
[WARN ] Interrupt received — stopped watching. Execution continues on the server.
[INFO ] Hint: Check with `np status`, or stop it with `np cancel -e <experiment_ref>`.

Sample output: submission

2026-08-21 16:15.40 [INFO ] [CLI] Starting Workflow Execution

Execution Plan:
  Steps:
    [1/2] graph_optimize
    [2/2] graph_quantize — scheme: W8-A8
  Profile:
    INPUT_MODEL, GRAPH_OPTIMIZE, OUTPUT_MODEL
  Evaluate:
    INPUT_MODEL (snr)
    GRAPH_OPTIMIZE (snr)
    OUTPUT_MODEL (snr)
  Total: 8 jobs

`np status`

Shows the current status of each job in an experiment. Use np status to check whether a pipeline submitted with np run is still pending or running, or has finished. This also applies if you started the run with --wait and then pressed Ctrl+C to stop watching it.

np status
np status --experiment <experiment_id>
np status --job <job_id>
np status --experiment <experiment_id> --kind evaluate
np status --evaluate <measurement_ref> --logs

Option	Required	Description
`--experiment`	No	Experiment ref_id. Fetch status directly from the Backend without directory detection
`--project`	No	Project ref_id. Fetch status directly from the Backend without directory detection
`--job`	No	Job ref_id. Fetch a single job's status directly from the Backend
`--evaluate`	No	Evaluate measurement ref_id. Show its status and metrics. Combine with `--experiment --kind evaluate` to list an experiment's evaluate measurements instead
`--profile`	No	Profile measurement ref_id. Show its status and metrics
`--analyze`	No	Analyze measurement ref_id (evaluation + analyze). Show its status and metrics
`--kind`	No	With `--experiment`: list that experiment's measurements of this kind (`evaluate` \| `profile` \| `analyze`)
`--logs`	No	Print the execution log below the status table. Applies to the experiment scope and to a single measurement (`--evaluate`/`--profile`/`--analyze <ref>`)

`np cancel`

This command is the only way to actually stop something running on the backend: pressing Ctrl+C in the CLI no longer cancels processing (see np run). np cancel stops all active processing for an experiment and marks unfinished child jobs as cancelled. This includes the pipeline execution itself, if pending or running, and any in-progress post-hoc evaluate or profile measurements.

np cancel                           # current experiment, with confirmation prompt
np cancel -e <experiment_ref> --yes  # target explicitly, skip the prompt

Option	Required	Description
`--experiment`, `-e`	No	Target experiment by ref_id instead of the current directory
`--yes`, `-y`	No	Skip the confirmation prompt

Sample output

$ np cancel
[ About to cancel ]
 Experiment  experiment_00
 ID          f1e2d3c4-b5a6-0987-6543-210987fedcba
 Run         running (2 of 3 steps completed)
 Profile     pending
 Evaluate    pending
Cancel this experiment? [y/N]: y
[INFO ] Requesting cancellation for experiment 'experiment_00'
[DONE ] Canceled experiment_00

A running job is not interrupted mid-step. The step in progress finishes, and cancellation takes effect before the next step starts. Completed step artifacts are preserved and recoverable with np export --level full. If nothing is running or queued, np cancel reports that there is nothing to cancel and exits without sending a request.

note

Cancelling a job still in the pending (queued) state is not supported yet but is planned for a future release.

`np report`

Displays optimization results. Scope is determined by current directory.

np report
np report --sort latency
np report --filter "snr > 30"
np report --detail

Option	Required	Description
`--project`	No	Project ref_id. Fetch report directly from Backend without directory detection
`--experiment`	No	Experiment ref_id. Fetch report directly from Backend without directory detection
`--sort`, `-s`	No	Sort by metric (for example, `latency`, `snr:desc`, `latency:asc,snr:desc`)
`--filter`, `-f`	No	Filter by condition (for example, `"snr > 30"`, `"latency < 100"`)
`--detail`, `-d`	No	Show step-level details under each experiment (project report only)
`--output`, `-o`	No	Show output-level detail tables (SNR by output tensor). Experiment level only
`--config`	No	Add Config column showing `run.yaml` identifier
`--json`	No	Output results as JSON
`--plain`	No	Output results as plain text without formatting

The top-level table shows the np run pipeline's own results, including which dataset produced each metric as its own column, distinct from the metric value. Each subsequent np evaluate or np profile execution appears in a separate table below the main table. The table shows the parameters and metrics for that execution.

Sample output: experiment-level

                                       Experiment: experiment_00
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Model             ┃ Type           ┃ Status  ┃ Memory(MB) ┃ Latency(ms) ┃ MACs ┃ Params ┃ SNR (vs input) ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ input_model       │ -              │ -       │     185.14 │       89.75 │ 4.1G │  25.6M │ -              │
│ 01_graph_optimize │ graph_optimize │ success │     185.14 │       74.07 │ 4.1G │  25.6M │ 121.06         │
│ 02_graph_quantize │ graph_quantize │ success │      46.28 │       34.48 │ 4.1G │  25.6M │ 0.18           │
└───────────────────┴────────────────┴─────────┴────────────┴─────────────┴──────┴────────┴────────────────┘

MACs and parameters are always shown alongside memory and latency. These measurements come from the same static analysis as mlia profiling, not from a separate step. On xnnpack-backend projects, Memory(MB) and Latency(ms) show as -, because mlia only produces MACs and parameters for xnnpack targets. Full latency and memory estimates from mlia are available only when targeting ethos_u (Alif E8). To get real latency and memory numbers on an xnnpack device, measure directly: see On-device profiling.

Post-hoc measurements

Anything you ran afterward with np evaluate or np profile follows as its own table per execution, below the main table, grouped under a Post-hoc Measurements (N) header. Failed runs are counted but hidden by default:

============================================================
Post-hoc Measurements (3)
============================================================
hidden: failed 6

[ np evaluate (post-hoc) — Target: 02_graph_quantize ]
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Started             ┃ Dataset                      ┃ Source (vs) ┃    MAE ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━┩
│ 2026-08-22 16:40:05 │ imagenet1k_eval_seed42_n5000 │ input_model │ 0.1246 │
└─────────────────────┴──────────────────────────────┴─────────────┴────────┘

[ np profile (post-hoc) — Target: 02_graph_quantize ]
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Started             ┃ Device              ┃ Runtime    ┃ Backend ┃ Method ┃ Latency(ms) ┃ Memory(MB) ┃ Weight Memory(MB) ┃ MACs ┃ Params ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩
│ 2026-08-22 16:46:21 │ raspberry_pi_5_16gb │ executorch │ xnnpack │ mlia   │           - │          - │                 - │ 4.1G │  25.6M │
└─────────────────────┴─────────────────────┴────────────┴─────────┴────────┴─────────────┴────────────┴───────────────────┴──────┴────────┘

Each np evaluate row shows the dataset and comparison source used for that specific call. Each np profile row shows the device/runtime/backend/method, with columns the method did not produce (for example latency and memory from mlia on xnnpack) shown as -.

`np export`

Exports experiment artifacts for deployment or reproduction. Defaults to L0 (compiled model only). Use --level to include additional artifacts.

np export                                    # L0 deploy — compiled model only (default)
np export --level config                     # L1 — add config files
np export --level result                     # L2 — add execution results
np export --level full                       # L3 — add intermediate models + logs
np export --level archive                    # L4 — add input model + datasets + env info
np export --experiment <experiment_id>       # Target a specific experiment

Option	Required	Description
`--experiment`, `-e`	No	Experiment ref_id to export. Skips directory detection
`--level`, `-l`	No	`deploy` (L0, default) / `config` (L1) / `result` (L2) / `full` (L3) / `archive` (L4)
`--generate-etrecord`	No	Generate an ExecuTorch ETRecord alongside the exported model
`--ethosu-system-config`	No	Ethos-U system config (Ethos-U targets only)
`--ethosu-memory-mode`	No	Ethos-U memory mode (Ethos-U targets only)
`--ethosu-target`	No	Ethos-U target (Ethos-U targets only)

Each level includes everything from the level below it, roughly: deploy is the compiled model alone; config adds run.yaml/project.json/dataset config; result adds execution results (report.json, per-job metadata); full adds intermediate per-step models and logs; archive adds the input model, pre-processed calibration/evaluation data, and environment info.

Sample output

$ np export
2026-08-22 15:30.00 [INFO ] [CLI] Exporting experiment artifacts
2026-08-22 15:30.00 [INFO ] [CLI] Fetching S3 artifacts (presigned GET) ...
2026-08-22 15:30.13 [DONE ] [CLI] Export completed.

[ Result Summary ]
 Level         deploy
 Extracted to  /path/to/workspace/my-project/experiment_00/artifacts/deploy

[ Result ]
  - model.pte

[ Next Steps ]
To include config or execution results:
  $ np export --level config
  $ np export --level result

`np visualize`

Opens the graph viewer (probe), a browser-based viewer for inspecting the model graph and comparing checkpoints. This command generates a link rather than opening a browser directly, and requires a browser session established using np visualize auth first.

np visualize                                  # Auto-detect from current directory
np visualize --experiment <experiment_id>     # Specific experiment
np visualize --job <job_id>                   # Specific job output
np visualize --compare <baseline_id> <target_id>  # Side-by-side comparison
np visualize --job <job_id> --component prefill   # One component of a multi-component model

Option	Required	Description
`--experiment`, `-e`	No	Target experiment path, ref_id, or resolved via `refs.json`
`--job`, `-j`	No	Target a specific job output
`--compare`, `-c`	No	Compare two experiments/jobs (first = baseline, second = target). Probe only. Errors if combined with `--tool model-explorer`
`--component`	No	Component to render, for multi-component models (for example `prefill`, `decode`): get names from `np jobs info`. Omit to get one link per component
`--tool`, `-t`	No	Visualization tool: `probe` (default, all formats, supports `--compare`) or `model-explorer` (VGF only, single-graph view; unsupported for `LLM` or `AUDIO` domain models)

`np visualize auth`

Bootstraps browser access to Probe/model-explorer. The visualization views require a session cookie; this subcommand exchanges your stored CLI credential for a short-lived bootstrap link/token that establishes it. Takes no arguments.

np visualize auth

Sample output

$ np visualize auth
Session bootstrap ready — use EITHER method (both establish the same session):

1) Open in browser (auto-establishes the session):
https://auth.your-deployment.netspresso.ai/api/v1/visualize/authorize?bootstrap=eyJhbGciOi...

2) Or paste this token into the page's auth field (same value as the end of the link above):
──────────────────── TOKEN — copy the line below ────────────────────
eyJhbGciOi...
─────────────────────────────────────────────────────────────────────

This link/token expires in about 179s. Use it promptly.

Duration	Meaning
~3 minutes	How long the bootstrap link/token itself is valid. Open it or paste it before it expires.
1 hour	How long the browser session lasts once established, checked only at first page load

The link and the token are the same value (the token is just the link's ?bootstrap= query parameter). Use whichever is convenient. Visualization URLs from np visualize itself do not expire on their own. As long as your browser session is live, they work regardless of when they were issued.

`np evaluate`

Runs post-hoc accuracy evaluation on a completed model, job, or experiment.

np evaluate <id> --dataset <name> --metric <METRIC>
np evaluate <id> --dataset <name> --metric MAP:iou_threshold=0.5
np evaluate <id> <id2> --dataset <name> --metric SNR --force

Option	Required	Description
`IDS...` (positional)	Yes	Target ID(s): `model_id`, `model_name`, `job_id`, or `experiment_id`. Multiple allowed
`--dataset`, `-d`	Yes	Dataset name for evaluation
`--metric`, `-m`	Yes	Metric to compute. Repeatable. Supports inline params: `METRIC:key=val`
`--source`, `-s`	No	Baseline model for comparison metrics (SNR, MSE, MAE). Default: `input_model`
`--as`	No	Force input type: `model`, `job`, or `experiment`
`--force`, `-f`	No	Force re-evaluation, bypassing the result cache
`--all`	No	When targeting an experiment, evaluate all candidates including `input_model`
`--num-samples`	No	Number of samples to evaluate on. Default: full dataset
`--gpu`, `-g`	No	GPU device (for example, `cuda:0`). Default: `cuda:0` (falls back to `cpu` if unavailable)
`--wait`	No	Wait for the evaluation(s) to finish (poll to completion), then print the result table
`--json`, `--plain`	No	Machine-readable output

Cache behavior

The same (artifact, dataset, metric, source) combination returns the cached result without rerunning. Use --force to override.

Sample output

$ np evaluate <job_id> --dataset imagenet1k_eval_seed42_n2 --metric ACCURACY --wait
2026-08-21 17:50.33 [INFO ] [Evaluate] Evaluating: 02_graph_quantize
...
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Model             ┃ Status  ┃ ACCURACY ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ 02_graph_quantize │ success │   0.7980 │
└───────────────────┴─────────┴──────────┘

`np profile`

Measures the latency and memory of one or more targets on the server.

np profile <id>...                         # omit ids to profile every target of the current experiment
np profile <id> --method mlia
np profile <experiment_id> --all --wait     # every optimized model, not just the best

Option	Required	Description
`id...` (positional)	No	Target IDs: job, model, or experiment. For an experiment ID, profiles only its best model unless `--all` is given. Omit entirely to profile every target of the experiment in the current directory
`--method`	No	`mlia` (the supported method for this delivery). See Profiler for measurement details
`--device`, `-d`	No	Target device alias to measure on (default: the project's configured device). Run `np devices ls` for aliases
`--runtime`, `-r`	No	Runtime that narrows down `--device`, when the same alias exists under several runtime/backend combinations
`--backend`, `-b`	No	Backend that narrows down `--device`, together with `--runtime`
`--force`	No	Measure again instead of reusing a past estimate
`--all`	No	For an experiment ID, profile every candidate model instead of just the best
`--as`	No	Force how the ID is interpreted: `model`, `job`, or `experiment`
`--wait`	No	Wait for completion and print the measurement table. Without it, the command submits and returns immediately with each target's status and a measurement ref. Multiple targets are polled sequentially, one at a time

--experiment is also accepted (deprecated) for backward compatibility: pass the experiment ID as a positional argument instead.

An mlia estimate for the same model/device is reused from an earlier measurement unless --force is given.

`np analyze sensitivity`

Shows module-wise sensitivity for a job, including signal-to-noise ratio (SNR), Kullback-Leibler divergence (KLD), kurtosis, and Pctl-Max. This is an expert option aimed at users comfortable with model internals. Values are read from a backend layerwise cache. This client never computes sensitivity locally.

np analyze sensitivity <job_id>
np analyze sensitivity <job_id> --component prefill

Option	Required	Description
`job_id` (positional)	Yes	Job ref_id to analyze, from `np jobs ls`'s `ID` column
`--metric`, `-m`	No	`snr` \| `kld` \| `kurtosis` \| `pctl_max`. Default `snr`
`--sort`	No	`metric` \| `topological` \| `name`. Default `metric`
`--dataset`, `-d`	No	Evaluation dataset ref_id used when the metric was computed
`--threshold`	No	Flag modules outside the acceptable range (opt-in)
`--component`, `-c`	No	Component identifier for multi-component models (for example `prefill`, `decode`). Required to disambiguate when the model has layerwise data for more than one component; ignored for single-component models
`--wait`	No	Wait for an on-demand recomputation to finish (poll to completion), then render the table. Ignored on a cache hit
`--format`, `-f`	No	`table` \| `json`. Default `table`

If the requested metric has not been computed yet, recomputation is submitted to the server and runs there. Recomputation is detached by default. The command submits and returns immediately; pass --wait to poll until it finishes.

np analyze sensitivity <job_id> -m kld              # submit and return
np analyze sensitivity <job_id> -m kld --wait       # submit and poll

AQ jobs do not support this. Activation quantization is not reflected in the graph, so per-layer sensitivity has nothing to attach to:

[WARN ] [CLI] AQ jobs do not support per-layer sensitivity analysis (activation quantization is not reflected in the graph).

A job with no cached data (and no successful recomputation yet) produces an error:

[ERROR] [CLI] [NP-CAP-404] Backend error (HTTP 400, code=FRS_005): Layerwise data not found: model_ref_id=<id>, project_ref_id=<id>

`np ls`

Lists post-hoc run history for a model, job, or experiment.

np ls --post-hoc <id>

Option	Required	Description
`--post-hoc <id>`	Yes	ID of the target (model / job / experiment) to list post-hoc run history for

Sample output

$ np ls --post-hoc <job_id>

02_graph_quantize (1 run(s)):
Run ID                              Command      Status   Started
20260821T175033_69785cad-7b5d...    np evaluate  success  2026-08-21 17:50

Command summary​

Auth and environment​

Resource management​

Execution​

Viewing results​

Global options​

np health ready​

Sample output​

np auth​

Sample output​

np workspace init​

Sample output​

np projects create​

Example: CV model​

Example: Hugging Face LLM​

np models ls​

Sample output​

np models register​

Sample output​

model_register.yaml​

np datasets ls​

Sample output​

np datasets register​

Sample output: success​

Sample output: rejected​

np devices ls​

Sample output​

np experiments create and np experiments detail​

Supported step values​

Sample output​

Sample output​

np jobs ls​

Sample output​

np jobs info​

Sample output​

Listing and inspecting resources​

np validate​

Sample output: pass​

np run​

Sample output: Ctrl+C​

Sample output: submission​

np status​

np cancel​

Sample output​

np report​

Sample output: experiment-level​

Post-hoc measurements​

np export​

Sample output​

np visualize​

np visualize auth​

Sample output​

np evaluate​

Cache behavior​

Sample output​

np profile​

np analyze sensitivity​

np ls​

Sample output​

Command summary

Auth and environment

Resource management

Execution

Viewing results

Global options

`np health ready`

Sample output

`np auth`

Sample output

`np workspace init`

Sample output

`np projects create`

Example: CV model

Example: Hugging Face LLM

`np models ls`

Sample output

`np models register`

Sample output

`model_register.yaml`

`np datasets ls`

Sample output

`np datasets register`

Sample output: success

Sample output: rejected

`np devices ls`

Sample output

`np experiments create` and `np experiments detail`

Supported step values

Sample output

Sample output

`np jobs ls`

Sample output

`np jobs info`

Sample output

Listing and inspecting resources

`np validate`

Sample output: pass

`np run`

Sample output: Ctrl+C

Sample output: submission

`np status`

`np cancel`

Sample output

`np report`

Sample output: experiment-level

Post-hoc measurements

`np export`

Sample output

`np visualize`

`np visualize auth`

Sample output

`np evaluate`

Cache behavior

Sample output

`np profile`

`np analyze sensitivity`

`np ls`

Sample output