CLI reference

This page describes each magnet subcommand. Two behaviours hold for every command:

1. Path arguments are always optional:

When no argument is provided, the commands act on the project containing the current working directory (found by walking up to the Magnet.toml).
When a .mag file is added as an argument, it defines the entry point, for example: magnet simulate src/plant.mag will use plant.mag as the top-level model.

2. Stages narrate on stderr:

check, build, and simulate write progress messages to stderr and results to stdout. The cargo build output is shown there as well.
With --format json, stdout contains only machine-readable JSON. Build output is suppressed unless compilation fails; compile failures are returned in-band as { ok: false, … } with exit code 0.
Color is disabled when any of these holds:
- stderr is not a terminal
- NO_COLOR is set
- TERM=dumb

Exit codes

An exit code says whose fault a failure is:

Code	Meaning
`0`	Success.
`1`	The model is at fault, as in the diagnostics.
`2`	`magnet` itself is at fault.

A generated crate that fails to build exits 2, because that is a bug in magnet and never in your model. The exception is an extern block whose Rust disagrees with its header, which exits 1.

`magnet new`

magnet new <name> [--no-git]
magnet new --rust <name> [--no-git]

Scaffolds a new Magnetite project in directory <name>/ with:

a manifest
a starter model
a .gitignore
a git repo, skipped with --no-git

Names start with a lowercase letter or _, followed by lowercase letters, digits, _ or -. Following Cargo’s rule, a control-lib package is imported as use control_lib. These names are refused:

core, the embedded stdlib
magnetite, magnetite-common and serde, which the generated crate depends on
main and lib, which Rust reserves for a crate root
Rust and magscript keywords

With --rust, creates <name>/ as a distributable custom block: a Rust crate with the magnetite runtime configured and the matching extern header in src/.

`magnet check`

magnet check [dir] [--format text|json]

Runs the compilation pipeline without writing anything and without invoking cargo:

parsing
model checking
code generation

`magnet build`

magnet build [dir] [--profile release|sim] [--model Name] [--format text|json]
magnet build [dir] --runtime fmi3 [--interface co-simulation|scheduled-execution] [--model Name]
magnet build [dir] --runtime embassy [--model Name]

Write the generated #![no_std] crate to target/codegen/<profile>/<name>/ and compile it.

The release (default) profile strips telemetry and XIL testing context and builds the deployable library.
The sim profile adds the telemetry structs and builds the simulation runner into target/codegen/runners/<model>/.
--format json prints { files, block_locations } instead of writing the crate.
--runtime exports the model for a runtime instead: fmi3 writes an FMU to target/export/, and embassy writes the glue a firmware depends on. It takes neither --profile nor --format.
With --runtime, the model is --model (a use path), else [deploy] model, else the one simulate would run.
--interface picks the FMU’s interface, Co-Simulation by default. Only fmi3 takes it.

`magnet simulate`

magnet simulate [dir] [--dt <s>] [--ticks N] [--input in.csv] [--model Name] [--param name=value]... [-o out.csv] [--format text|json]

Compiles the selected model with the sim profile, builds its native runner, and writes one CSV row per tick.

--dt defaults to the manifest’s [simulate] dt; a step with @every needs neither.
--ticks defaults to the number of rows in --input, else to [simulate] end over the sample time. With none of the three, the command fails.
Input CSV columns are matched by header name. Declared inputs must be present; otherwise-unfed inputs default to zero.
Parameters are built by the entry’s constructor, its params item, with each argument at its default. An argument with no default must be supplied with --param, and the refusal lists each one.
--param sets an argument of the entry’s constructor, or an element or field of one: scale=2.0, gains[1]=0.5, ic.rate=9.0.
A dotted name that reaches into an instance, such as pid.kp=2.0, is refused, because a child’s arguments are its parent’s decision. Route the value through a root argument instead: params Rig(kp: f64 = 2.0) { Self { pid: Pid(kp) } }, then --param kp=3.0.
Model selection is resolved from these, and --model overrides it:
- the requested .mag file
- models with params
- the top-level model
The runner is generated in target/codegen/runners/<model>/, beside the sim crate in target/codegen/sim/<name>/, and built with Cargo.
Cargo incremental compilation is preserved: model or params changes may rebuild the runner, while --param changes do not.
--format json prints { columns, rows } on stdout; -o writes the CSV of --format text to a file.

`magnet flash`

magnet flash [dir] [--chip name] [--firmware dir] [--model unit::Path]

Builds the production crate in target/codegen/release/<name>/.
Runs cargo build --release in the firmware crate.
Flashes the binary with probe-rs download --chip.

The firmware crate’s .cargo/config.toml selects the target. Defaults come from [deploy] in Magnet.toml; flags override the corresponding keys.

`magnet blocks`

magnet blocks [--path dir] [--global] [--format text|json]

Prints shipped blocks and blocks from project dependencies as a table, or the raw catalog with --format json. --global prints only shipped blocks.

`magnet add`

magnet add <name> [--git url [--tag v | --rev v | --branch v]] [--path dir]

Adds a dependency to Magnet.toml. Git sources are fetched before the manifest is changed. A bare name such as magnetite-ext selects a known library. Existing entries report Unchanged.

Git dependencies are checked out under .magnet/deps/<name>/ when the project first loads. Magnet uses git from PATH and its configured credentials. Existing checkouts support offline builds.

Branches and unqualified refs remain at their first resolved commit until magnet update; builds report that commit on stderr. See Packages and libraries for pinning rules.

`magnet remove`

magnet remove <name>

Removes a dependency from Magnet.toml and its .magnet/deps/ checkout.

`magnet update`

magnet update [dep] [--path dir]

Re-fetches git dependencies and reports commit changes. Branches and unqualified refs require this command to advance; tag and rev dependencies are re-resolved on each build.

`magnet sync`

magnet sync [dir]

Reconciles the DSL with its graph view in .magnet/. If both changed, the DSL takes precedence.

`magnet watch`

magnet watch [dir]

Runs sync on project changes until interrupted.

`magnet serve`

magnet serve [dir] [--port N] [--open]

Starts the project kernel, serving the GUI and WebSocket on localhost (default port 7317) and syncing connected clients.

`magnet gui`

magnet gui [dir] [--port N]

Runs serve --open, starting the kernel and opening the editor in a browser.

`magnet license`

magnet license activate <key> [--name name]
magnet license status [--min-days N]
magnet license refresh
magnet license install <file>
magnet license fingerprint
magnet license deactivate

These commands only move this machine onto or off a seat. Granting and revoking seats happens on the dashboard.

activate puts this machine on the seat the key belongs to. The installer runs this for you with the key from the dashboard’s install command. --name sets what the machine is called there. Left out, it is named for its platform and the first six characters of its fingerprint, such as macos-3f9a1c; the hostname is never sent.
status says what this machine’s license is worth, renewing first if the license is due for it. --min-days N exits 1 unless the license is good for at least N more days, for a job that wants to fail before a build does.
refresh renews the license with the key this machine already holds. A key is typed once, with activate, and the machine renews itself from then on.
install takes a license file issued for a machine that cannot reach the licensing service, checked out elsewhere and brought here. A file issued for a different machine is refused.
fingerprint prints this machine’s fingerprint, the same one status and the dashboard show.
deactivate takes this machine off its seat, freeing the slot for another, and removes the license files here.

`magnet version`

magnet version

Prints this magnet’s version, as magnet 0.1.0 on stdout. Requires no license.

`magnet self-update`

magnet self-update

Replaces the CLI with the newest release on its channel:

A prerelease build follows prereleases and takes the next stable release when one lands.
A stable build never sees a prerelease.

Reports Unchanged if already current. The download is accepted only if it carries our signature, checked against a key compiled into magnet.

Requires no license, and installs to ~/.magnet/bin, where the installer put the first one. On Windows, the running executable is renamed before replacement, so this works from magnet gui.

`magnet uninstall`

magnet uninstall [--yes]

Removes ~/.magnet/bin/magnet and the installer receipt. Preserves these files in ~/.magnet/:

license.lic
license.key
bin/env
bin/env.fish

Prints the removed and preserved files and manual purge instructions. Prompts unless --yes is set; no license is required.