Run the CLI with npx
[⏱️ ~2 min] Run one `mdk` command from the registry without installing it
TL;DR
npx --yes @tetherto/mdk-cli <command>runs onemdkcommand with nothing installed on your PATH- Pin an exact version in CI so every run executes the same build, for example
npx --yes @tetherto/mdk-cli@0.14.0 status - The authorization gate still applies: a stack runs
mdk rbac initbefore its firstmdk run, however the CLI was started
Overview
npx fetches the published CLI into the npm cache and runs it once. That suits commands that need no project, such as
mdk skill add or mdk create worker, checks in CI against a committed mdk.yaml, and trying a version before you adopt it.
For day-to-day operation of a stack, install the CLI instead: every npx call resolves the package again, and
mdk run keeps the terminal in the foreground for as long as the stack is up.
Packages scaffolded this way depend on the published MDK packages, so the project's own npm install reaches the registry.
That differs from a source checkout, where mdk create worker links the packages in the checkout.
Prerequisites
- Node.js >=24 (LTS)
- npm 11 (< 12)
- Network access to the npm registry on the first run of each version
The first run downloads the CLI and the MDK runtime it bundles. Later runs of the same exact version reuse the npm cache.
Run a command
Try mdk status to check your environment:
npx --yes @tetherto/mdk-cli status--yes skips the install prompt that npx shows before fetching a package it has not seen; npm assumes it when standard
input is not a terminal.
Without a version, npx runs the newest published release, unless the project has @tetherto/mdk-cli installed. When
mdk onboard or mdk create creates the project's package.json, it lists the CLI in devDependencies, so npx
runs that installed copy. Neither adds or updates the CLI dependency in an existing package.json. To run a specific
release either way, add its version after the package name, for example npx --yes @tetherto/mdk-cli@0.14.0 status.
Commands that write into a project, such as mdk onboard, mdk create and mdk skill add, run from the directory you are
working in; the rest take --dir <path> to point at a project elsewhere. Only mdk --version and mdk version are global.
Choose the binary explicitly
When the binary name matters, for example in a script that calls mdk by name, use the package form:
npx --yes -p @tetherto/mdk-cli mdk --versionUse it in CI
Pin an exact version. A tag such as @latest or a caret range can resolve to a build already in the runner's cache, so two
runners can execute different builds from the same workflow line; an exact version forces one build everywhere. The repo's
own link checker is pinned for the same reason.
Replace <version> with the exact published CLI version your workflow uses, for example 0.14.0:
npx --yes @tetherto/mdk-cli@<version> validate worker rig
npx --yes @tetherto/mdk-cli@<version> statusIn a Worker or app package's own repository, check the package directory with --path:
npx --yes @tetherto/mdk-cli@<version> validate worker --path .
npx --yes @tetherto/mdk-cli@<version> validate app --path .A listing request is reviewed against the listing criteria, which add flags to these commands; run each one as the criteria give it.
- Cache
~/.npmbetween jobs so later runs skip the download - Pass
--prefer-onlinewhen a run must re-check the registry rather than trust the cache - Run only non-interactive commands:
mdk validate,mdk status, andmdk runagainst a committedmdk.yaml. Runmdk onboardinteractively before committing the configuration.
What still applies
npx changes how the CLI starts, not what it enforces. A fresh stack is set up in the same order as with an installed
mdk, each step from the project directory or with --dir:
npx --yes @tetherto/mdk-cli onboard # interactive: writes mdk.yaml
npx --yes @tetherto/mdk-cli rbac init # edits mdk.yaml in place: binds the CLI to admin, grants each app its permissions
npx --yes @tetherto/mdk-cli runThen, from a second terminal, create the first operator the same way:
npx --yes @tetherto/mdk-cli user add <name> --admin. The site security blueprint covers what
spec.rbac holds and how to go beyond the starter policy.
Troubleshooting
Missing project configuration
mdk status reports a missing mdk.yaml; it does not create one.
Expected output from mdk status when mdk.yaml is missing:
MDK status (no stack)
Environment
Node v24.x.x ok
Package manager npm
Spec mdk.yaml missing
No mdk.yaml found in <directory>.
Run `mdk onboard` to create one.Running mdk run or mdk rbac init without mdk.yaml fails:
error: No mdk.yaml found in <directory>.
Run `mdk onboard` to create one.For an existing project, check that you are in its directory or pass --dir <path>. If you deleted mdk.yaml, restore it
from Git or a backup to recover the project's configuration.
For a new project, run onboarding from the project directory:
npx --yes @tetherto/mdk-cli onboardOnboarding interactively creates mdk.yaml and package.json. It creates a new configuration; it does not recover a deleted one.
Kernel refuses to start because the policy binds nobody
Run mdk rbac init before starting a fresh stack. Without an initial policy binding, mdk run refuses to boot the Kernel.
Expected error:
spec.rbac binds nobody, so the Kernel would boot with nobody able to administer it: `mdk rbac init` would be refused.
Run `mdk rbac init` first, then `mdk run`.Initialize the policy, then start the stack from the project directory:
npx --yes @tetherto/mdk-cli rbac init
npx --yes @tetherto/mdk-cli runOnboarding exits without creating a project
mdk onboard needs an interactive terminal. Run it locally in a terminal, then commit the generated configuration for CI.
Dashboard template cannot be fetched
mdk create dashboard fetches its template from GitHub at the tag matching the CLI version. Check that git is on your PATH
and that you can reach GitHub. A named dashboard lands in apps/<name>.
Dashboard dependencies fail to install
On npm 11.0 to 11.5 the first npm install in the dashboard crashes on peer resolution.
mdk create dashboard retries with --legacy-peer-deps and prints that it did, so the npm error above
that line can be ignored. If the retry fails too, the command reports npm's exit code and leaves the
scaffold in place: upgrade to npm 11.6 or newer and run npm install in apps/dashboard.
npm offers an upgrade to npm 12
Stay on npm 11 to avoid npm 12 restrictions on Git dependencies. The upgrade notice does not require action.
Next steps
- Install the CLI: put
mdkon your PATH for daily use - Run a mining site end to end: see a stack running with mock hardware
- Explore CLI commands and flags: the full command surface