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/cliTo pin this release:
npm install --global @nm-lang/cli@0.7.1Create a program and run the local simulator
nm --version
nm init main.nm
nm run main.nm --jsonExamples 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 enCreation 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 --jsoncheck 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-visibilityNew 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.1Python
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
1nm test main.nm --name "balanced qubit" --json2nm test main.nm --report-format junit --output results.xml3nm test main.nm --report-format sarif --output results.sarif4nm test main.nm --watch --jsonUnknown/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.
nm bridge --allow-feature hamiltonianEvolution --allow-feature measurementGroupingRun a local, bounded JSON request with original source, independent caller permissions and complete training/uncertainty evidence.
nm doctor --jsonCompare observed CLI/Core and local LSP/MCP metadata with the loaded version and capability manifest; unobserved editor/server installations are explicit.
nm run main.nm --sweep sweep.json --experimental-parameter-groups --jsonExecute explicit zip/cartesian axes with shared work budgets and replayable source evidence.
nm check main.nm --jsonParse and validate a program with optional explicitly negotiated experimental language support.
nm run main.nm --shots 1024 --jsonExecute with explicit shot, output, and optional independently negotiated experimental language capabilities.
nm debug main.nm --breakpoint 6 --jsonRecord a bounded source-mapped debug session with verified breakpoints.
nm fmt main.nm --checkFormat or verify source-preserving output.
nm lint main.nm --strictReport diagnostics and enforce strict warning policy.
nm test main.nm --experimental-property-assertions --jsonRun tests, properties and snapshots with exact selection, JSON/JUnit/SARIF reports, and Node-host dependency watching.
nm explain main.nm --jsonExplain diagnostics and improvement opportunities.
nm transpile main.nm --target superconducting --calibration calibration.json --jsonLower to a target-native gate basis with optional calibrated placement.
nm estimate main.nm --ftqc --budget nm-budget.jsonPrint logical and fault-tolerant resource estimates and optionally fail closed against a versioned budget artifact.
nm export main.nm --to qasm3 --strict --jsonExport 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.
nm benchmark main.nm --optimizers gd,adam --steps 8 --csvBenchmark bounded objective or supervised workloads and emit versioned JSON or CSV evidence.
nm checkpoint create main.nm --steps 8Create a legacy exact-GD checkpoint or opt-in stateful deterministic optimizer continuation artifact.
nm checkpoint resume training.checkpoint.json --additional-steps 8Validate and continue a legacy GD or stateful checkpoint without mutating the input artifact.
nm checkpoint model training.checkpoint.json --name resumed-modelConvert validated checkpoint state into the existing model-package contract; createdAt reflects invocation time.
nm init main.nmCreate a guarded runnable starter.
nm init bell-project --template bell --name bell-projectCreate a complete project from shared source bytes without overwriting existing files.
nm package build main.nmBuild a portable learning-package artifact.
nm package validate package.jsonValidate a learning-package contract.
nm package list --jsonList exact registry packages and trust metadata.
nm package inspect std.bell@0.1 --jsonInspect source, integrity, license, and trust metadata.
nm package install std.bell@0.1 --output std_bell.nm --jsonInstall an integrity-checked exact package.
nm package sign release.json --output release.signed.json --jsonCreate an Ed25519 release attestation.
nm package verify release.signed.json --jsonVerify a signed package release against trusted keys.
nm workspace snapshot main.nmCreate a deterministic read-only workspace snapshot.
nm workspace share main.nmPrint a bounded fragment-first snapshot URL.
nm workspace validate workspace.snapshot.json --jsonValidate snapshot integrity with stable diagnostic codes.
nm lock main.nmCreate a canonical exact dependency lock from experimental package imports.
nm lock main.nm --lock nm-lock.json --jsonValidate missing, stale, changed, and non-exact source dependencies against a lock.