Skip to main content
Language v0.2.0 · Preview

N/M command-line reference

Operational commands for creating, checking, testing, running, packaging, exporting, transpiling, and sharing reproducible N/M workspaces.

Public npm installation

Install the N/M command line

Create and run a local N/M program without a repository checkout or a TypeScript build.

Requires Node.js 20 or newer. Release checks use Node.js 22.23.1.

npm package 0.7.1 targets N/M language 0.2.0. An untagged install selects the default latest channel; use @0.7.1 to reproduce this release. The distribution channel does not change the language's preview maturity status. The VS Code extension has a separate distribution version.

npm install --global @nm-lang/cli

To pin this release:

npm install --global @nm-lang/cli@0.7.1

Create a program and run the local simulator

nm --version
nm init main.nm
nm run main.nm --json

Examples run on a local simulator. Installation does not establish physical QPU access or make every capability stable.

Personal, educational and commercial use is free. QuantumSoftware retains rights to its package code; modification and redistribution require separate permission. Your N/M programs and results remain yours. Read LICENSE.txt in the installed package.

Tools introduced in 0.6.0

The numerical operations, workspace auto-import and complete project templates introduced in 0.6.0 remain available in current CLI 0.7.1 with Core 0.7.0. The language contract stays 0.2.0 and preview/experimental maturity remains unchanged.

Create a complete project

Choose Bell, parametric training or numerical computing. Each project includes src/main.nm, shared src/helper.nm, tests/main.test.nm, nm-workspace.json and a README.md in the selected language.

Terminal

npm install --global @nm-lang/cli@0.7.1nm init bell-project --template bell --name bell-project --locale ennm init parametric-training-project --template parametric-training --name parametric-training-project --locale ennm init numerics-project --template numerics --name numerics-project --locale en

Creation does not overwrite occupied directories or run source automatically. The numerics README explicitly lists --experimental-classical-functions and --experimental-typed-classical-values. Neither the manifest nor a template grants experimental permissions; saved false settings remain off.

Check, run and test the Bell project

After creating the Bell example with the commands above, enter its folder in the same terminal. JSON version output should show cliPackageVersion 0.7.1, corePackageVersion 0.7.0 and language 0.2.0. These commands are for the Bell template; follow each other template's own README.

Terminal

cd bell-projectnm --version --jsonnm check src/main.nmnm run src/main.nm --jsonnm test tests/main.test.nm --json

check validates source and imports; run produces 256 local Bell simulation shots with only 00/11 outcomes expected; test verifies both state probabilities through the shared helper circuit. Successful commands exit with code 0. The parametric template's DSL train block executes during ordinary nm run; the separate finite-shot training host selected with --train is a different workflow.

Import from your workspace

Start typing a public function, record or enum from the same workspace and accept its completion. The editor inserts the required use workspace.… line. Private symbols stay excluded; alias, visibility and cycle checks remain. Open-file suggestions remain available while the disk index is being prepared.

Requires extension or standalone language server 0.6.0. Add these two files to the generated project's src folder and open both in the editor. Enable classicalFunctions and typedClassicalValues; this public declaration also needs moduleVisibility. The default VS Code profile enables them; previously saved false values must be changed explicitly.

src/math.nm

module guide_math;public fn double(value: Float) -> Float {  return value * 2.0;}

src/import-demo.nm

module import_demo;use workspace.guide_math;fn main() {  let q = qreg[1];  let result: Float = double(0.5);  return result;}

The main example shows the accepted completion. To try it, remove use workspace.guide_math; and shorten double to dou. With the cursor after dou, press Ctrl+Space and select double from workspace.guide_math. Completion fixes the name and inserts the import together. Check the source module when multiple symbols have the same name.

The result variable has value 1.0. If no suggestion appears, check that you opened the project folder, the files are inside the manifest's src source root, and the relevant features are enabled. Auto-import is an editor action. The guide's CLI example makes the same grants explicit; saved or supplied false feature choices are not enabled automatically.

Terminal

nm check src/import-demo.nm --experimental-classical-functions --experimental-typed-classical-values --experimental-module-visibility

New numerical operations

eigvecsh
Returns column eigenvectors of a Float/Complex Hermitian matrix in the same order as eigvalsh. Phase and degenerate eigenspace bases are not unique. Parameter-dependent analytic eigenvector derivatives are unsupported.
solve
Computes first-order real derivatives of A*x=b through A*dx=db-dA*x. Primal and derivative right-hand sides share a pivoted factorization within one call. Complex and second derivatives are outside this scope.
lstsq
Uses column-pivoted QR for full-column-rank Float least squares on square or tall systems. Wide/rank-deficient matrices and parameter-dependent analytic derivatives are unsupported.

Existing 1–16 matrix dimensions, 256-element and shared work budgets remain unchanged. Extension tests and recorded debugging do not start the separate finite-shot training host; select that host with CLI --train.

Open the matrix and derivative guide →

Use the local CLI from Python and Jupyter

CLI 0.7.1 includes the stdlib bridge and optional nm_jupyter extension in its python/ directory. Install the npm package locally in your notebook/Python project and run this example from that project directory. Python 3.10+ and Node.js on a trusted PATH are required.

Terminal

npm install @nm-lang/cli@0.7.1

Python

from pathlib import Pathimport sys adapter_dir = Path.cwd() / "node_modules/@nm-lang/cli/python"sys.path.insert(0, str(adapter_dir.resolve()))from nm_bridge import NMClient client = NMClient(locale="en", timeout=30)source = "module notebook_check;\nfn main() {\n  let q = qreg[1];\n  H(q[0]);\n  return q;\n}"result = client.check(source)print(result.success)

This example only checks source. Source checking, ordinary execution and the separate training host use distinct explicit calls; opening a notebook or importing the module does not execute source. Saved records grant no permissions; shot budgets and confidence intervals remain. There is no separate PyPI publication; the local wheel identity is 0.0.0.dev0. The Python adapter is not included in the VSIX.

For optional cells, install IPython 9.17.1 in a Python 3.11+ environment. With the client above ready, run %load_ext nm_jupyter in a separate cell, then explicitly check the source using the cell below. No global kernel or automatic startup is installed.

Jupyter

%%nm --client client --checkmodule notebook_check;fn main() {  let q = qreg[1];  H(q[0]);  return q;}

Selected tests, watching and CI reports

Use @nm-lang/cli 0.3.0 or later for test selection, watching and CI reports. --name matches the exact name; --id uses the JSON report identity for the same input path and source lines. Both flags can repeat and their union executes. Unselected test blocks do not run; shared setup and original lines remain. Syntax and capability validation still cover the complete source.

CLI

nm test main.nm --name "balanced qubit" --jsonnm test main.nm --report-format junit --output results.xmlnm test main.nm --report-format sarif --output results.sarifnm test main.nm --watch --json

Unknown/stale selections fail with NM-TEST-SELECT-001. Nested checks cannot be selected directly; select their top-level enclosing check. Empty suites and failed execution exit 1. --report-format json|junit|sarif selects stdout format; --output replaces the named .json/.xml/.sarif report each run in an existing parent directory. --json cannot combine with a non-JSON report format.

The Node CLI host runs immediately with --watch, then watches dependency .nm files and workspace manifests, debounces changes and runs without overlap. With --json, stdout is NDJSON events: run, sequence, exitCode, report and diagnostics. JUnit/SARIF watching requires --output. Ctrl+C or SIGTERM closes watchers.

In @nm-lang/cli 0.3.0 and later, use nm doctor --json or nm doctor --locale tr to check the loaded CLI/Core and local LSP/MCP packages. Package, language and protocol versions are compared separately. VS Code installations and running servers are not queried; unobserved tools are not verified.

CLI 0.1 command contract

Help output, documentation, the spec API, packaged CLI exports, output kinds, filesystem mutation, determinism, and exit codes are generated from one registry. Successful commands return 0; invocation, validation, provider, or execution failures return 1.

success: 0failure: 1
nm bridge --allow-feature hamiltonianEvolution --allow-feature measurementGrouping

Run a local, bounded JSON request with original source, independent caller permissions and complete training/uncertainty evidence.

output: jsondeterminism: runtime-timingfilesystem: neverJSON
01
nm doctor --json

Compare observed CLI/Core and local LSP/MCP metadata with the loaded version and capability manifest; unobserved editor/server installations are explicit.

output: human-or-jsondeterminism: filesystem-dependentfilesystem: neverJSON
02
nm run main.nm --sweep sweep.json --experimental-parameter-groups --json

Execute explicit zip/cartesian axes with shared work budgets and replayable source evidence.

output: human-or-jsondeterminism: runtime-timingfilesystem: neverJSON
03
nm check main.nm --json

Parse and validate a program with optional explicitly negotiated experimental language support.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
04
nm run main.nm --shots 1024 --json

Execute with explicit shot, output, and optional independently negotiated experimental language capabilities.

output: human-or-jsondeterminism: runtime-timingfilesystem: neverJSON
05
nm debug main.nm --breakpoint 6 --json

Record a bounded source-mapped debug session with verified breakpoints.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
06
nm fmt main.nm --check

Format or verify source-preserving output.

output: human-or-sourcedeterminism: byte-stablefilesystem: optional
07
nm lint main.nm --strict

Report diagnostics and enforce strict warning policy.

output: humandeterminism: byte-stablefilesystem: never
08
nm test main.nm --experimental-property-assertions --json

Run tests, properties and snapshots with exact selection, JSON/JUnit/SARIF reports, and Node-host dependency watching.

output: human-or-jsondeterminism: byte-stablefilesystem: optionalJSON
09
nm explain main.nm --json

Explain diagnostics and improvement opportunities.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
10
nm transpile main.nm --target superconducting --calibration calibration.json --json

Lower to a target-native gate basis with optional calibrated placement.

output: source-or-jsondeterminism: byte-stablefilesystem: neverJSON
11
nm estimate main.nm --ftqc --budget nm-budget.json

Print logical and fault-tolerant resource estimates and optionally fail closed against a versioned budget artifact.

output: jsondeterminism: byte-stablefilesystem: neverJSON
12
nm export main.nm --to qasm3 --strict --json

Export QASM, Quantikz, raw AST JSON (json), versioned JSON IR (ir), or executable PennyLane Python; QASM JSON retains source sidecars; QASM3 also includes conformance evidence; PennyLane JSON retains required source sidecars.

output: source-or-jsondeterminism: byte-stablefilesystem: neverJSON
13
nm benchmark main.nm --optimizers gd,adam --steps 8 --csv

Benchmark bounded objective or supervised workloads and emit versioned JSON or CSV evidence.

output: source-or-jsondeterminism: runtime-timingfilesystem: neverJSON
14
nm checkpoint create main.nm --steps 8

Create a legacy exact-GD checkpoint or opt-in stateful deterministic optimizer continuation artifact.

output: jsondeterminism: byte-stablefilesystem: neverJSON
15
nm checkpoint resume training.checkpoint.json --additional-steps 8

Validate and continue a legacy GD or stateful checkpoint without mutating the input artifact.

output: jsondeterminism: byte-stablefilesystem: neverJSON
16
nm checkpoint model training.checkpoint.json --name resumed-model

Convert validated checkpoint state into the existing model-package contract; createdAt reflects invocation time.

output: jsondeterminism: runtime-timingfilesystem: neverJSON
17
nm init main.nm

Create a guarded runnable starter.

output: humandeterminism: filesystem-dependentfilesystem: always
18
nm init bell-project --template bell --name bell-project

Create a complete project from shared source bytes without overwriting existing files.

output: human-or-jsondeterminism: filesystem-dependentfilesystem: alwaysJSON
19
nm package build main.nm

Build a portable learning-package artifact.

output: jsondeterminism: byte-stablefilesystem: neverJSON
20
nm package validate package.json

Validate a learning-package contract.

output: humandeterminism: byte-stablefilesystem: never
21
nm package list --json

List exact registry packages and trust metadata.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
22
nm package inspect std.bell@0.1 --json

Inspect source, integrity, license, and trust metadata.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
23
nm package install std.bell@0.1 --output std_bell.nm --json

Install an integrity-checked exact package.

output: human-or-jsondeterminism: filesystem-dependentfilesystem: alwaysJSON
24
nm package sign release.json --output release.signed.json --json

Create an Ed25519 release attestation.

output: human-or-jsondeterminism: filesystem-dependentfilesystem: alwaysJSON
25
nm package verify release.signed.json --json

Verify a signed package release against trusted keys.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
26
nm workspace snapshot main.nm

Create a deterministic read-only workspace snapshot.

output: jsondeterminism: byte-stablefilesystem: neverJSON
27
nm workspace share main.nm

Print a bounded fragment-first snapshot URL.

output: urldeterminism: byte-stablefilesystem: never
28
nm workspace validate workspace.snapshot.json --json

Validate snapshot integrity with stable diagnostic codes.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
29
nm lock main.nm

Create a canonical exact dependency lock from experimental package imports.

output: jsondeterminism: byte-stablefilesystem: neverJSON
30
nm lock main.nm --lock nm-lock.json --json

Validate missing, stale, changed, and non-exact source dependencies against a lock.

output: human-or-jsondeterminism: byte-stablefilesystem: neverJSON
31
Open Playground