CLI reference

Overview

mdk is the command-line tool that scaffolds, runs and checks an MDK stack from the mdk.yaml spec in a project directory. This page lists every command with its arguments, flags and defaults, in the groups mdk --help uses. It states what each command takes and does, not how to sequence them: the install guide puts mdk on your PATH, the Worker guide runs a stack end to end, and the first operator page creates the user who signs in. Every command reads mdk <verb> [noun], and mdk <command> --help prints the same options from the binary.

Every command that reads an existing project takes --dir <path>, the directory holding mdk.yaml, and defaults to the current directory. mdk onboard is the exception: it creates the project and asks for the directory as its first prompt, so it has no --dir. Commands that print data honor the global --output flag.

Global flags

Set up

mdk onboard

Sets up a new project interactively: checks the environment, asks which Workers, apps and dashboard to include, writes mdk.yaml, package.json, .gitignore and a project README.md, and prints the commands to run it. The policy it writes binds the CLI's own account and each app, so the stack boots; the first operator is created afterwards. It takes no flags and needs an interactive terminal.

Build

mdk create worker <name>

Scaffolds a Worker Plugin (mdk-contract.json, handlers and a mock device) into workers/<name>, links it into package.json and adds it to mdk.yaml under spec.workers with a mock device. <name> is lowercase letters, digits, ., _ or -.

mdk create app <name>

Scaffolds an app (mdk-app.yaml, a plugin/ route table with controllers, and a starter UI built into ui/) into apps/<name>, links it into package.json, adds it to mdk.yaml under spec.apps and grants it the Kernel access its manifest requests in spec.rbac. <name> follows the Worker rule.

mdk create dashboard [name]

Scaffolds the MDK UI shell into apps/dashboard, named <stack>-dashboard from mdk.yaml. With a name it lands in apps/<name> instead. Inside the monorepo the template is copied locally; elsewhere it is fetched from GitHub at --ref.

mdk add app <source> and mdk add worker <source>

Installs a package from npm or GitHub with npm install --ignore-scripts --save-exact, checks it with the same rules as mdk validate, then adds it to mdk.yaml under spec.apps or spec.workers. A refused package leaves mdk.yaml and package.json unchanged. A path on disk is refused: reference a local package by path in mdk.yaml instead.

<source> is one of:

An app installs as service account app:<name>, with a credential under .mdk/credentials/apps/ and a role in spec.rbac granting exactly what its mdk-app.yaml requests. A Worker without a bundled mock is added without mock: true.

mdk validate app [name] and mdk validate worker [name]

Checks a package and lists every problem; exits 1 when it is not valid. Name a component mdk.yaml declares, or check any package directory with --path. For an app the check covers mdk-app.yaml, its version against package.json, the permission rules, the route table, every handler file and the UI build; a named app's grant in spec.rbac is checked too. For a Worker it covers package.json and mdk-contract.json against the schema and its semantic rules, with every handler resolved on disk and compiled but not run.

The Worker testing guide lists every smoke.config.js field for a Worker, and the apps guide covers the app smoke checks.

Run

mdk run [target] [name]

Starts the Kernel, Workers, app runtimes and Gateway from mdk.yaml, or one component. Runs in the foreground; Ctrl+C stops everything in reverse boot order. Each Kernel, Worker and app runs once per project, held by a lock under .mdk/run/. A spec.rbac that binds nobody is refused before boot, with mdk rbac init as the fix.

mdk run mcp reads these optional keys from spec.mcp in mdk.yaml:

spec.mcp.token and spec.mcp.identity are refused: each agent signs in with its own service account, and spec.rbac decides what it may call.

mdk status

A one-shot report on the environment (Node version, package manager, mdk.yaml validity, whether every declared package resolves) and the stack (Kernel, Gateway, each Worker with its state, health and device count, each app). It starts, stops and repairs nothing; its one write is the CLI's caller key under .mdk/trusted-keys/.

Auth

spec.rbac in mdk.yaml is the only place policy is written, and no matching rule means denied. The security blueprint covers the policy itself; the first operator page walks the sign-in sequence. Every command in this group takes -d, --dir <path> (default .).

mdk rbac

apply and show exit 1 when the Kernel is down or refuses the policy. init still writes mdk.yaml with the Kernel down and exits 0, since the Kernel applies the file when it next starts; it exits 1 when an app's grant cannot be written. All three exit 1 on an invalid spec.rbac.

mdk user

Users live in the Kernel's token issuer, so every subcommand needs the Kernel running.

Flags of mdk user add:

mdk user passwd takes --password-stdin too. A password is never accepted as a flag value, and the Kernel refuses one shorter than twelve characters.

mdk serviceaccount

mdk sa is the alias. A service account signs in with its own key: app:<name> for each app, created by mdk add app, and a named account per AI agent. The private key stays in .mdk/credentials/ and never ships in a package.

mdk login <username>, mdk logout, mdk whoami

mdk login signs in to the Kernel's token issuer and keeps the session in .mdk/session.json, readable by you alone. While it lasts, mdk status, mdk user, mdk sa and mdk rbac act as you, with what spec.rbac binds you to; an expired session is an error, never a quiet return to the service account. mdk logout ends the session, and mdk whoami prints who the CLI acts as, honoring -o json and -o yaml.

Agent enablement

mdk skill add

Installs the MDK Developer Skill suite into the project, so a coding agent knows MDK conventions.

Meta

mdk version

Prints the package name and version to stdout. mdk --version prints the version alone.

Next steps

• Install the CLI: put mdk on your PATH from npm, or from a source checkout to work on the CLI itself
• Run your Worker with the CLI: the commands in sequence, from a declared package to a dashboard and an agent
• Create the first operator: the user every dashboard and route sign-in needs
• Read the CLI package notes: how the CLI is built, tested and run from source