MDK Logo

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 one mdk command 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 init before its first mdk 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 --version

Use 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> status

In 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 ~/.npm between jobs so later runs skip the download
  • Pass --prefer-online when a run must re-check the registry rather than trust the cache
  • Run only non-interactive commands: mdk validate, mdk status, and mdk run against a committed mdk.yaml. Run mdk onboard interactively 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 run

Then, 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 onboard

Onboarding 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 run

Onboarding 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

On this page