Run the CLI with npm

To run a single mdk command without installing anything — in CI, or to try a version before you adopt it — use npx instead.

TL;DR

Operate the stack from your terminal
Install mdk on your PATH with npm install -g @tetherto/mdk-cli
Confirm it with mdk --version

mdk is MDK's command-line tool for standing up and operating a stack from your terminal. It scaffolds a stack (mdk create), boots it (mdk run), and reports its health (mdk status), all driven by the mdk.yaml spec mdk onboard writes for you.

Prerequisites

Node.js >=24 (LTS)
npm 11 (< 12)

Install

Install the published CLI from npm. A source checkout is only needed to work on the CLI itself.

Put `mdk` on your PATH

If mdk --version already prints a version, skip to verifying your install.

A. Install from npm

npm install -g @tetherto/mdk-cli

npx @tetherto/mdk-cli@latest <command> runs a single command without installing anything globally, which suits CI and one-off scaffolding.

B. Install from a source checkout

Contributors who are changing the CLI's own source build it and link that build onto their PATH instead.

git clone https://github.com/tetherto/mdk.git && cd mdk/packages
npm install
cd cli && npm run build && npm link

To pin a tagged release, pick a tag from mdk tags and check it out before installing, for example git checkout -b local/v0.12.1 v0.12.1.

Verify the install

mdk --version

Run project commands from your project

Commands such as mdk skill add and mdk onboard write into your current directory, so run them from the app or UI project you are working in. Only mdk --version is global.

Command groups

Commands grouped by purpose:

Group	Commands
Set up	`mdk onboard`
Build	`mdk create worker\|app\|dashboard`, `mdk add app\|worker <source>`, `mdk validate app\|worker <name>`
Run	`mdk run [target]`, `mdk status`
Auth	`mdk rbac init\|apply\|show`, `mdk user`, `mdk serviceaccount`, `mdk login`, `mdk logout`, `mdk whoami`
Agent enablement	`mdk skill add`
Meta	`mdk version`

The CLI's command surface documents the full flag reference.

Update

npm install -g @tetherto/mdk-cli@latest

Update a source checkout

How a source checkout updates depends on whether it tracks main or is pinned to a tag. Run every command from the repository root, mdk/, and build only the CLI workspace: npm run build at the root builds every workspace in the monorepo.

On main, pull the latest commits:

git pull
npm install && npm --workspace packages/cli run clean && npm --workspace packages/cli run build

On a pinned tag, such as a local/v0.12.1 branch, git pull fails with There is no tracking information for the current branch, since a branch created from a tag tracks no remote branch. Fetch the tags and check out the new one instead, for example v0.13.0:

git fetch --tags
git checkout -b local/v0.13.0 v0.13.0
npm install && npm --workspace packages/cli run clean && npm --workspace packages/cli run build

The earlier npm link still points at packages/cli, so mdk --version reports the new version without linking again.

Uninstall

npm rm -g @tetherto/mdk-cli

Next steps

Try the demo to see a stack running end to end
Run a Worker in a stack with a dashboard and an agent, with no app code
Create the first operator once a stack runs, so the dashboard and every route have someone to sign in as
Build with your agent so a coding agent knows MDK conventions