Docs · Everyday use

CLI reference

Every public command, with its flags, the platform it runs on, and what it does when it refuses. Anything not listed here does not exist in this build.

How to read this#

nodeau <command> [arguments] [flags]
nodeau <command> --help        # always current, for the binary you have

Conventions used throughout:

• Platform — Linux means Linux with an NVIDIA GPU; macOS means Apple Silicon; Both means the command works the same on either.
• Plan — only stated where a capability is actually gated. Most commands need no account at all.
• Arguments in UPPER CASE are required; [BRACKETS] are optional.

Namespaces#

Workload commands take --namespace/-n, defaulting to nodeau-dev. Unless you have created others, that is the only one you will use. -A / --all-namespaces looks across all of them where it is offered.

Exit codes#

Five, deliberately. A script needs to answer three questions without parsing text: did it work, is this my fault, and should I try again?

The distinction between 3 and 4 is the one that matters: a script that retries on failure should retry on 4 and never on 3.

nodeau doctor uses a narrower contract of its own: 0 everything passed or only warnings, 1 something failed, 2 called wrongly.

nodeau batch wait uses 0 finished, 1 failed, cancelled or timed out.

--json#

Thirty commands take --json. As a rule: every command that prints a table also takes --json, and commands that only perform an action do not.

The JSON is a stable contract — field names in it are part of the CLI's interface, and reason codes inside it will not be renamed without a breaking change. Use it rather than parsing human output, which is written for people and is expected to change.

--json never implies consent. A command that would change the machine still asks, or refuses and tells you to pass --yes.

Setting up#

nodeau install#

nodeau install [flags]

Check the machine, show a plan, and set up what is missing. Both platforms, with genuinely different bodies — see Linux and macOS.

On Linux it installs, when absent: the NVIDIA Container Toolkit, K3s, the NVIDIA device plugin, the per-device GPU driver, and Nodeau's own control plane. When they are already there it adopts them, uses them as found, and records that it did — which is what makes uninstall safe.

It will never install, upgrade, replace or remove your NVIDIA driver, and never touches Secure Boot, the bootloader, the kernel command line, any partition, or a Kubernetes cluster it did not create.

Running it again is safe: it re-checks everything, skips what is done, does not regenerate your API key, and never re-decides who owns a component.

Failure states. A blocking preflight check exits 3 and names the check. On Linux a missing or broken NVIDIA driver stops the install rather than being fixed. With no terminal attached and no --yes, it refuses rather than acting unasked.

nodeau join#

nodeau join CODE [flags]

Join this machine to an existing fleet as a worker. Linux. Needs FeatureMultiNode — Home Pro or Business on the machine that invited it.

Get the code from the machine that already runs Nodeau (nodeau fleet invite). This machine needs an NVIDIA GPU with a working driver and must be able to reach the other machine on your network. If it already runs a cluster of its own, Nodeau stops and says so rather than destroying it.

A Mac cannot join a fleet. See adding and operating machines.

nodeau doctor#

nodeau doctor [flags]

Diagnose this installation and explain anything that is wrong. Both. Every check is read-only: doctor never installs, configures, mounts, starts or stops anything.

Two halves. The host — is this machine capable of running Nodeau. The installation — is Nodeau itself working: its control plane, the agent on each machine, whether every machine's GPU report is fresh enough to schedule against, whether the models on disk still verify, and what your services and batch jobs are doing.

Exit 0 everything passed or only warnings · 1 something failed · 2 called wrongly. Codes are listed under health and diagnostics.

nodeau environment#

nodeau environment [--json]        # alias: nodeau env

Print what Nodeau has detected about this machine: operating system, processor, memory, GPUs, network, and which disks Nodeau is allowed to write to and which belong to another operating system. Both. Reads only.

nodeau version#

nodeau version [--json]

The build identity of this binary: version, commit, build date, channel, Go version and platform. Both.

nodeau update#

nodeau update [flags]

Compare this machine's Nodeau with the published release channel. Both. By default it only looks.

Nodeau never updates itself in the background, and a machine that cannot reach the internet keeps working exactly as it is. See updating and release channels.

nodeau uninstall#

nodeau uninstall [flags]

Remove Nodeau's own components, keeping everything Nodeau did not install. Both. The full plan is printed before anything happens, and each destructive option is named for exactly what it destroys. See uninstalling.

There is deliberately no flag that means "remove more" without saying what.

Running models#

nodeau quickstart#

nodeau quickstart [flags]

Download a model, start it, and print a working curl command. Linux. Everything it does is one of the other commands. See Quickstart.

nodeau run#

nodeau run MODEL|SERVICE [flags]

Start a model on one of your GPUs and print how to use it. Both — this is the supported vocabulary on Linux and macOS alike.

Given a model id it picks a GPU that can hold it, starts it, waits for it to load and prints an endpoint. Given something already running it just brings the local endpoint back. If the model is not downloaded it tells you the size and the licence and asks first.

The endpoint binds 127.0.0.1 and nothing else. By default it installs a user service so it survives closing the terminal; --foreground runs it here instead.

nodeau run qwen3.5-4b-q4km                       # a catalog model
nodeau run qwen-local                            # bring an existing one's endpoint back
nodeau run my-model --task embed --port 8081     # an imported model, as an embedder

Exit codes. 0 running, with an endpoint · 2 the model or service name was not recognised · 3 refused, and that will not change on its own · 4 still starting, and ran out of time to wait.

nodeau ps#

nodeau ps [flags]          # alias: nodeau list

Every workload using a GPU — models you are serving and batch jobs alike — with where each one is and what it is doing. Both.

nodeau status#

nodeau status [flags]

The state of every Nodeau workload and local endpoint. Both.

Nothing here is read from a cache. The workload state comes from the cluster, the endpoint state from the service manager, and "answering" from an actual connection to the port — so a stale record cannot make this report something that is not true.

Flags: --all-namespaces/-A, --namespace/-n, --json.

nodeau stop#

nodeau stop SERVICE [flags]

Stop serving a model locally. Both. By default this stops the local endpoint and leaves the model loaded on its GPU, so starting again is instant.

Your downloaded model files are never touched by any of these.

nodeau restart#

nodeau restart SERVICE [flags]

Restart the model behind a service so it re-reads its configuration. Linux.

The model server reads its configuration — including your API key — once, when it starts. A regenerated key, or any change to a mounted file, does not take effect until the process restarts. Nothing is reconfigured and nothing is deleted except the running pod. Expect a short gap while the model reloads into VRAM.

Flags: --wait (default true), --timeout (default 10m), --namespace/-n.

nodeau logs#

nodeau logs WORKLOAD [flags]

Read what a workload is printing, without needing kubectl. Linux.

nodeau logs qwen-local                     # the model server's own output
nodeau logs my-batch                       # a batch job's worker
nodeau logs --system nodeau-controller     # one of Nodeau's own components

Prompts, completions and batch records are never written to a log, so they cannot appear here.

nodeau dashboard#

nodeau dashboard [flags]

Serve a local dashboard showing hardware, models, running services and plan. Both. Binds loopback only and requires a token, printed in the URL and exchanged for a session cookie the first time you open it.

The page is compiled into the binary: nothing to install, nothing to download, and it works with no internet connection at all. It is read-only apart from one action — it can stop a batch job.

Flags: --addr (default 127.0.0.1:7371, must be loopback), --cache-dir.

nodeau endpoint serve#

nodeau endpoint serve [flags]

Run the loopback reverse proxy in the foreground until interrupted. Both. This is what the generated user service runs; use it directly to see why an endpoint will not start.

Flags: --service, --namespace, --model, --port (default 8080, 0 lets the OS choose), --upstream (resolved from the service when omitted).

nodeau service#

nodeau service get [NAME] [flags]     # alias: nodeau svc
nodeau service explain NAME [flags]
nodeau service apply -f FILE [flags]

Work with GPUService objects directly. Linux. This is a development-mode CLI: it talks to the Kubernetes API using your kubeconfig, with your permissions.

• get lists services, or shows one. Flags: --all-namespaces/-A, --namespace/-n, --json.
• explain shows the reasoning behind Nodeau's decision, including the VRAM arithmetic. Everything printed comes from the object's status, written by the controller when it decided — this command does not re-run the calculation.
• apply creates or updates a service from a YAML manifest (-f - for stdin). It does not admit the workload here; the controller admits it asynchronously and records the decision in status.

nodeau placement explain#

nodeau placement explain WORKLOAD [flags]

Why a workload is where it is, and what the alternatives would have cost. Linux. Flags: --namespace/-n, --json. See placement.

Models#

nodeau model and nodeau models are the same command.

nodeau model list#

nodeau model list [flags]          # alias: ls

Models Nodeau can serve, and what is downloaded. Both. Shows the curated catalog with each model's role, hardware rung, size and status, then your own imported models separately — different trust classes, listed separately.

Flags: --all (include deprecated and legacy models), --cache-dir, --namespace/-n (only show custom models in one namespace), --json.

nodeau model info#

nodeau model info MODEL [flags]

Licence, provenance and measured configurations. Both.

The measurements are the interesting part, and an empty list is a real answer: it means every decision about this model is computed rather than observed. Each row states its scope — whether the figure counted the whole device or one process — because the two are different quantities.

Flags: --cache-dir, --namespace/-n, --json.

nodeau model install#

nodeau model install MODEL [flags]

Download a model from its publisher and verify it. Both.

Nothing is downloaded until you agree: the size, licence and source are shown first. An interrupted download resumes. A file that fails verification is moved aside rather than deleted — so the evidence survives — and rather than left in place, so the next run cannot mistake it for a good one.

Flags: --consent (agree without being asked, for scripts), --verify (only re-verify what is already downloaded; download nothing), --cache-dir.

nodeau model verify#

nodeau model verify MODEL [flags]

Read the whole file and recompute its SHA-256. Both.

Presence is not integrity. Worth running on a machine that has been power-cycled or has had storage trouble: a corrupted model loads, serves fluent-looking answers and reports healthy. This checks this machine; each node verifies its own copy continuously and publishes the result, which nodeau model status shows.

nodeau model status#

nodeau model status [MODEL] [flags]

The fleet's view of models: which machine holds which weights, whether the bytes on each machine have been checked, which GPUs are big enough, and what is using them. Linux.

The GPU columns answer is this card big enough, judged as if the card were free of Nodeau workloads. Whether it is free right now is shown separately, because "too small" and "busy" call for completely different actions.

Flags: --context-size (default 4096), --parallel (default 1), --namespace/-n, --cache-dir, --json.

nodeau model remove#

nodeau model remove MODEL [flags]      # alias: rm

Delete the weights for one model, on this machine only. Both.

Nodeau checks first that no service references the model, and refuses by name if one does. It refuses just as firmly when it cannot reach the cluster to check: not knowing whether something is in use is a reason to stop, not a reason to proceed. Only the one model's artifact is touched.

Flags: --yes, --namespace/-n, --cache-dir.

nodeau model import#

nodeau model import PATH --alias NAME [flags]

Bring your own GGUF model into Nodeau. Linux (qualified). See bring your own model.

--alias and --no-register cannot be used together.

nodeau model qualify#

nodeau model qualify MODEL [flags]

Prove on your own hardware what a custom model can actually do. Linux.

Qualification uses free capacity and never evicts a healthy workload. If your cards are busy, admission refuses and the run reports it rather than waiting forever.

Batch inference#

Linux only. Needs FeatureBatchJobs — Home Pro or Business. On macOS these commands refuse by name. See batch inference.

nodeau batch submit#

nodeau batch submit FILE --model MODEL [flags]

Submit a JSONL file of requests.

--workers and --gpus answer different questions, and mixing them up costs throughput rather than raising an error. See workers and GPUs.

nodeau batch status#

nodeau batch status NAME [flags]

One batch job in detail. Flags: --namespace/-n, --json.

nodeau batch list#

nodeau batch list [flags]          # alias: ls

Flags: --all-namespaces/-A, --namespace/-n, --json.

nodeau batch wait#

nodeau batch wait NAME [flags]

Block until the job reaches a final state, then exit. The exit code is the outcome, so it composes with a shell:

nodeau batch wait my-job && nodeau batch results my-job

0 the job finished · 1 it failed, was cancelled, or the wait timed out. Flags: --timeout (default 24h), --namespace/-n.

nodeau batch results#

nodeau batch results NAME [flags]

Download the results, one JSON object per line. Written to a file by default — these are your model's answers, and printing them to a terminal by accident is how they end up in scrollback, a screenshot or a pasted issue.

Flags: --output/-o (default NAME-results.jsonl), --stdout, --namespace/-n.

nodeau batch cancel#

nodeau batch cancel NAME [flags]

Stop a batch job. Results already produced are kept and remain available. Nodeau waits for the model server to actually exit before releasing the GPU, so a cancelled job may take a few seconds to finish stopping. Flags: --namespace/-n.

Your machines#

nodeau fleet invite#

nodeau fleet invite [flags]

Print a code that adds another machine to your fleet. Linux. Needs FeatureMultiNode — Home Pro or Business.

The code is a credential for as long as it lives: paste it into the other machine's terminal, not into a chat log. It expires on its own whether or not anyone uses it.

Flags: --expires-in (default 15m), --address (the address the new machine should reach this one on; defaults to this machine's LAN address).

nodeau fleet list#

nodeau fleet list [--json]         # alias: ls

Every machine in your fleet and the GPUs in it. Linux.

nodeau fleet remove#

nodeau fleet remove MACHINE [flags]

Take a machine out of the fleet — retired, failed or sold. Linux.

Nodeau removes its cluster membership, the storage and identity it generated for it, and the credential that let it reconnect, then frees the plan slot it was using. Workloads placed on the machine block removal; stop them first, or pass --force if the machine is already gone.

The machine's own installation is not touched. Rejoining afterwards needs a fresh invitation, which is the point — a removed machine must not be able to reappear on its own.

Flags: --dry-run, --force, --yes, --json.

nodeau fleet connect#

nodeau fleet connect [flags]

Let Nodeau Cloud show you this fleet from anywhere. Linux. Requires an account (nodeau login).

Your machines reach out. Nothing ever connects in: there is no inbound port, no callback and no remote shell, and this command opens none. What leaves is what a person operating machines needs — which machines exist, what is plugged into them, what is running and whether anything is wrong. What you compute never does.

Nothing about inference depends on it.

Flags: --yes, --no-linger (do not offer to keep the connector running when you are logged out).

nodeau fleet disconnect#

nodeau fleet disconnect

Stop and remove the fleet connector. Linux. Nothing else changes; this machine stays linked to your account for entitlements — nodeau logout is what unlinks it.

nodeau fleet status#

nodeau fleet status [--json]

Whether this fleet is reporting to Nodeau Cloud. Linux.

nodeau scheduling mode#

nodeau scheduling mode [efficiency|balanced|performance] [flags]

Show or set how Nodeau chooses where work runs. Linux. With no argument it shows. Flags: --node <name> (set for one machine instead of the fleet), --json.

nodeau scheduling constraints#

nodeau scheduling constraints [flags]

Show or set the hard limits Nodeau must respect on a machine. Linux.

Flags: --node, --power-budget <W>, --idle-watts <W>, --max-accelerators <n>, --deny-device <uuid>, --allow-device <uuid>, --clear, --json. See hard constraints.

nodeau scheduling drain / undrain#

nodeau scheduling drain   --node MACHINE
nodeau scheduling undrain --node MACHINE

Stop placing new work on a machine, without touching what runs there; and put it back into service. Linux. Undraining does not move anything back.

nodeau governance#

nodeau governance [flags]

Show or set your organisation's limits on this fleet. Linux — on a native installation it refuses and says so. With no flags it shows the current policy.

Lowering a quota does not stop anything that is already running. See organisation limits.

nodeau health#

nodeau health [--json]
nodeau health history [flags]

How each machine is doing — processor, memory, storage and network — together with anything that needs attention. Linux; on a native installation both refuse by name.

history prints one machine's recorded telemetry. Flags: --machine, --since (default 1h), --resolution, --metric (repeatable), --device (repeatable), --max-points, --json.

Storage is how full a filesystem is and nothing more — Nodeau reads no drive health data. See health and diagnostics.

nodeau power#

nodeau power [--json]
nodeau power set --device UUID --limit WATTS
nodeau power set --device UUID --clear

Show what each GPU is allowed to draw and what it is drawing; and set one card's software power limit. Linux. set is local: it applies to a card in the machine you run it on and never crosses the network.

It writes no firmware, no VBIOS, no voltage and no clocks. See power limits and budgets.

Keys, accounts and plans#

nodeau auth show#

nodeau auth show [--quiet]

Print the local API key, creating one if this is the first time. Both.

Written for substitution, so the bare key is the only thing on stdout and anything explanatory goes to stderr:

export NODEAU_API_KEY="$(nodeau auth show)"

--quiet/-q prints only the key, with no notices on stderr.

nodeau auth token#

nodeau auth token SERVICE [flags]

Print the token to use against one service's endpoint. Linux. Unlike auth show, this checks which credential the service actually enforces and refuses rather than printing one that would be rejected.

Flags: --export (print a shell export line you can eval), --namespace/-n.

nodeau auth rotate#

nodeau auth rotate [--yes]

Generate a new local API key, discarding the current one. Both. Every saved curl command, script and SDK configuration using the old key stops working immediately. The running endpoint does not need restarting: it forwards whatever Authorization header it receives and never reads the key file itself.

nodeau auth publish#

nodeau auth publish SERVICE [flags]

Make the local API key the one a service enforces. Linux. This is the fix for an endpoint that rejects the key auth show prints — which happens when the service references a Secret Nodeau did not publish.

The model server reads its key file once at startup, so the workload restarts. Expect a short gap while the model reloads into VRAM. Flags: --yes, --namespace/-n.

nodeau login#

nodeau login [flags]

Link this installation to a Nodeau account. Both. Optional — Nodeau runs completely without one.

You are never asked to paste a token. Nodeau shows a short code, you approve it in a browser you are already signed in to, and this machine receives its own credential directly.

nodeau logout#

nodeau logout [--json]

Remove this machine's account link. Both. It does not stop anything: inference, batch and every local capability keep working, on the free Home plan. It is a local operation — the installation still exists in your Nodeau account until you remove it there.

nodeau plan show#

nodeau plan show [--json]          # alias: nodeau entitlement show

The current plan, its capabilities and its limits. Both.

nodeau plan refresh#

nodeau plan refresh [--json]

Fetch a current entitlement from Nodeau Cloud. Both. Run it after changing plan, and to renew before the current one expires.

A failed refresh changes nothing: the entitlement already on the machine keeps working until it expires, and an installation with no entitlement at all runs the free Home plan with every safety and integrity check intact.

nodeau plan set#

nodeau plan set --from-file FILE      # or - for stdin

Install a signed entitlement token. Both. Most people want nodeau login instead. The token is read from a file or stdin, never from a command-line argument, so it does not reach your shell history or the process list.

nodeau plan export / import#

nodeau plan export [FILE] [-o FILE]
nodeau plan import FILE [--json]

Carry an entitlement to a machine with no internet. Both.

The entitlement names the installation and organisation it was issued for, so a file exported from one machine is not a licence another machine can use. An imported entitlement goes through exactly the same checks a fetched one does and is never less verified. Nothing secret is in the file.

Support#

nodeau support bundle#

nodeau support bundle [flags]

Write a sanitised diagnostic archive to the current directory. Both. The bundle is written to your disk and sent nowhere; Nodeau has no endpoint to upload it to. Flags: --output/-o, --namespace/-n.

See support bundles for exactly what is included and what is excluded.

Not documented here#

nodeau completion generates a shell completion script and is standard Cobra behaviour.

Two commands are hidden and are not part of the supported surface: nodeau fleet refresh-connector, which the installer calls for you, and — on macOS only — nodeau native, a diagnostic that bypasses the catalog, consent and the endpoint. Use the ordinary commands instead; they do the same work on both platforms.

Documentation for the current published build, the beta channel. Something here wrong or missing? Tell us — a report from a machine we have never seen is the most useful thing we get.