Quick start
np installs directly using pip and connects to the Arm AI Model Optimizer backend over HTTPS. np creates and submits experiment configurations and retrieves results, but optimization, quantization, evaluation, and profiling run on the backend.
Prerequisites
| Item | Requirement |
|---|---|
| Python | 3.11 or later |
| Network | HTTPS access to the Arm AI Model Optimizer backend API and auth server |
Installation
1. Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
2. Install the CLI
pip install arm-ai-model-optimizer
Sample output:
Collecting pydantic>=2.0.0 (from arm-ai-model-optimizer-=2.1.5)
Collecting typer>=0.12.0 (from arm-ai-model-optimizer-=2.1.5)
Collecting huggingface-hub>=0.30.0 (from arm-ai-model-optimizer-=2.1.5)
... (resolving further dependencies)
Successfully installed arm-ai-model-optimizer-2.1.5
3. Verify the install
np --version
# arm-ai-model-optimizer 2.1.5
np --help
If np --help shows the following command list, the install succeeded.
Usage: np [OPTIONS] COMMAND [ARGS]...
Arm AI Model Optimizer - AI model optimization toolkit
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version -V Show version and exit │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ report Show optimization results │
│ status Show experiment/project run status │
│ run Submit the experiment run to the backend (--wait to follow, --dry-run to preview) │
│ validate Validate a run.yaml against the backend │
│ export Export experiment artifacts for deployment or reproduction │
│ evaluate Evaluate model(s) on the server │
│ profile Measure latency and memory of model(s) on the server │
│ cancel Cancel a running or queued experiment on the backend │
│ analyze Analyze model layerwise sensitivity (backend cache lookup only). │
│ auth Manage authentication (login / logout / status) │
│ health Check backend connectivity health │
│ devices Manage devices and supported combinations │
│ datasets Manage datasets for model optimization │
│ models Manage models │
│ projects Manage projects for model optimization │
│ experiments Manage experiment run configurations │
│ jobs Inspect pipeline jobs (per-experiment) │
│ workspace Manage workspaces for model optimization │
│ ls List post-hoc run history (np ls --post-hoc <id>) │
│ visualize Generate a visualization link for models │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Docs: https://developer.arm.com/dev-docs/arm-ai-model-optimizer
Each group has its own subcommands. Run np <group> --help to view them:
| Group | Subcommands |
|---|---|
auth | login, logout, status |
workspace | init |
models | ls, register |
datasets | ls, register |
devices | ls |
projects | create, ls, info |
experiments | create, detail, ls, info |
jobs | ls, info |
analyze | sensitivity |
visualize | auth |
health | ready |
The following commands have no subcommands: validate, run, status, report, export, evaluate, profile, cancel, and ls.
See CLI reference for details on every option.
Initial configuration (environment variables)
np reads backend and auth server connection information from environment variables at runtime. The values for these are already baked into the tool.
| Variable | Required | Description |
|---|---|---|
NP_CLIENT_API_URL | Required | The Arm AI Model Optimizer backend API address (accepts NP_ENTERPRISE_API_URL as an alias) |
NP_CLIENT_AUTH_API_URL | Required | The auth server address. This is a separate host from the backend, and is used by np auth and session refresh. |
NP_ENTERPRISE_FE_URL | Required | A web portal address used to display portal links |
NP_MODEL_EXPLORER_URL | Required | Needed for np visualize --tool model-explorer |
NP_CLIENT_API_TIMEOUT | Optional | Backend request timeout in seconds. The default is 15.0. |
LOG_LEVEL | Optional | The CLI log verbosity. The default is INFO. |
All 4 required variables must point at the same environment. If NP_CLIENT_API_URL and NP_CLIENT_AUTH_API_URL point at different environments, the backend responds normally but authentication fails. Each variable also needs the https:// prefix. A bare hostname, for example model-explorer.netspresso.devplatform.arm.com, fails when the CLI tries to build a link. If a supplied value does not include the prefix, add it before you export the variable.
export NP_CLIENT_API_URL="https://api.netspresso.devplatform.arm.com"
export NP_CLIENT_AUTH_API_URL="https://auth.netspresso.devplatform.arm.com"
export NP_ENTERPRISE_FE_URL="https://app.netspresso.devplatform.arm.com"
export NP_MODEL_EXPLORER_URL="https://model-explorer.netspresso.devplatform.arm.com"
If you were given a .env file with this delivery, load it into the current shell instead of exporting each variable by hand:
set -a; source .env; set +a
Check connectivity and log in
Create and copy a token in the AI Portal as described in Manage access tokens. Use that complete value in place of <token> below.
np health ready # verify the Backend is reachable
np auth login '<token>' # log in with the token you copied
np auth status # confirm you're authenticated
You must have a valid login before you run any command, including np workspace init. After you log in, your session refreshes automatically. You do not need to log in again until the session is explicitly revoked. See CLI Reference: np auth for credential storage and error messages.
Running np health ready without setting NP_CLIENT_API_URL produces this error:
[ERROR] [CLI] Environment variable NP_CLIENT_API_URL (or NP_ENTERPRISE_API_URL) is not set.
Initialize a workspace
Initialize a workspace from your working directory. This creates a workspace/ subdirectory there, registers it as the workspace root with the backend, and generates a ready-to-run sample project.
mkdir my-workspace && cd my-workspace
np workspace init
Sample output
[INFO ] [CLI] Initializing New Workspace
[INFO ] [CLI] Checking directory availability...
[INFO ] [CLI] Created workspace root: /path/to/my-workspace/workspace
============================================================
[Phase 1] Sample Project Setup
============================================================
[INFO ] [CLI] Generating sample project...
============================================================
Summary
============================================================
[INFO ] [CLI] Workspace initialized successfully.
[ Result Summary ]
Workspace Path /path/to/my-workspace/workspace
Sample Experiment /path/to/my-workspace/workspace/sample_project/experiment_00
Model resnet18_pt2_pytorch_static_fp32
Calibration sample_image_calib_seed42_n2
Evaluation sample_image_eval_seed42_n2
[ Next Steps ]
Navigate to your workspace and try the sample experiment:
$ cd /path/to/my-workspace/workspace/sample_project/experiment_00
$ np run
The workspace root is stored globally in ~/.config/np/config.json. There is only ever one active workspace on each machine. Running np workspace init again from any directory reports the already-registered path rather than creating a second one.
[INFO ] [CLI] Initializing New Workspace
[INFO ] [CLI] Checking directory availability...
[INFO ] [CLI] Workspace already initialized: /path/to/my-workspace/workspace
[ Next Steps ]
To create a new project, run:
$ cd /path/to/my-workspace/workspace
$ np projects create
To point it at a different location, see Reset the local configuration.
Reset the local configuration
If the workspace registration gets into a bad state, or you want a clean start, delete the local configuration file and re-initialize.
# Reset local workspace config
rm ~/.config/np/config.json
np workspace init
| To reset | Delete | Impact |
|---|---|---|
| Workspace path registration | ~/.config/np/config.json | Resets only the workspace root location. Rerun np workspace init. |
| Local project/experiment refs | ~/.config/np/refs.json | Resets the mapping between the local folder and the backend ref_id. Existing project and experiment folders need --experiment and --project with an explicit ref_id to reconnect. |
| Login credential | ~/.config/np/auth.json | Removed by np auth logout. Rerun np auth login <credential>. |
| Full reinstall | The CLI itself (pip uninstall netspresso) | Repeat the installation steps |
Next steps
Your workspace already has a ready-to-run sample project generated on initialization.
- Tutorial 1: sample project: Validate, run, and inspect the sample project in a few commands (start here)
- Tutorial 2: Computer vision (CV) model: Build a project from scratch, with devices and schemes explained
- Tutorial 3: large language model (LLM): Optimize a language model with the advanced quantize (AQ), graph optimize (GO), and graph quantize (GQ) steps
- Tutorial 4: Bring Your Own Model (BYOM) and Bring Your Own Data (BYOD): Bring your own model and dataset
- Concepts: The relationship between workspaces, projects, experiments, and jobs, and the compatibility matrix
- Diagnosis and log reference: Exit codes, common issues, and error code lookup