The desktop command is your primary interface for managing an OWD project from the terminal. It handles everything from environment setup and development to package installation and validation.
It ships in @owdproject/core (packages/core/bin/desktop.js). In the official client monorepo:
pnpm desktop # same as: node ./packages/core/bin/desktop.js
owd is a deprecated alias for desktop. Use pnpm desktop in scripts and docs.Running pnpm desktop with no subcommand opens the interactive TUI (control panel).
| Key | Action |
|---|---|
| m | Command menu |
| s | Start Nuxt dev server |
| x | Stop dev server |
| R | Restart dev server |
| w | Save catalog/theme changes to desktop.config.ts |
| d | Toggle User (npm) / Dev (git clone) install mode |
| g | Settings (GitHub user for fork clones) |
| r | Refresh package list from GitHub |
| b | Run pnpm run generate |
| q / Esc | Quit |
desktop devStart the dev server. Resolution depends on current working directory:
# From client monorepo root → reference desktop/
pnpm desktop dev
# From an app or theme package → that package’s playground/
cd apps/app-about
pnpm desktop dev
# Force playground even when cwd might resolve elsewhere
pnpm desktop dev --playground
Requires a Nuxt project with modules: ['@owdproject/core'] and desktop.config.ts.
desktop initScaffold a new OWD desktop project (uses the template blueprint), install dependencies, then open the control panel:
desktop init my-desktop
desktop init . # current directory
Equivalent to npm create owd for new projects outside the monorepo.
desktop addInstall an app, theme, or extension module and register it in desktop.config.ts (and desktop/package.json when using the reference desktop).
desktop add app-todo
desktop add theme-nova
desktop add module-fs
desktop add module-persistence --npm
desktop add app todo # → @owdproject/app-todo
desktop add theme paper
desktop add module fs
Kinds are inferred from the name when omitted (app-*, theme-*, module-*).
--from)--from | Behaviour |
|---|---|
| (omit) | npm registry (default) |
npm | npm registry |
owdproject | Clone github.com/owdproject/<package> (monorepo dev) |
<github-user> | Clone github.com/<user>/<package> |
<user>/<repo> | Explicit GitHub repo |
<git-url> | Full clone URL |
| Flag | Effect |
|---|---|
--npm | Force npm (skip git) |
--dev, --workspace | Clone into apps/, themes/, or packages/ in the monorepo |
--branch <name> | Git branch to clone |
--dry-run | Print plan only |
-h, --help | Usage |
Examples:
desktop add app-todo --npm
desktop add theme-paper --dev
desktop add module-persistence --from dxlliv
Still supported; prefer desktop add:
desktop install-app @owdproject/app-todo # → desktop add app-todo
desktop install-theme theme-nova
desktop install-module module-fs
desktop validateCheck that a package matches the OWD 3.4 module layout (exports, playground, peers, CI patterns).
desktop validate # cwd package, or all apps/themes/modules at repo root
desktop validate .
desktop validate apps
desktop validate themes/theme-paper
| Flag | Effect |
|---|---|
--json | Machine-readable output |
--strict | Warnings fail the run |
--smoke | Run dev:prepare + nuxt build playground (slow, CI) |
From the monorepo root:
pnpm validate:modules
| Area | Examples |
|---|---|
| Structure | src/module.ts, src/runtime/, no duplicate root runtime/ |
| Exports | exports["."].import, optional development → ./src/module.ts |
| Scripts | dev:prepare, prepack, validate, no prepare script |
| Register plugin | defineDesktopApp, desktop-*-register, server guard |
| Playground | deps on your package + @owdproject/core, ssr: false, <Desktop /> |
| Launch (optional) | autoStartPlaygroundApps, no import.meta.dev guard |
| CI (standalone repos) | client checkout overlay; avoid standalone nypm with workspace:* |
Fix errors before npm publish. Warnings are recommended fixes (launch plugin, CI, centering). Full code list: core PLAYGROUND.md.
desktop template (maintainers)Regenerate template/ (output of npm create owd) from the blueprint and reference desktop:
pnpm template:sync
# or
desktop template
desktop template --dry-run
desktop template --check # CI: fail if template/ drifted
pnpm scriptsThese wrap the same tooling from the client root:
| Script | Effect |
|---|---|
pnpm dev | nx run desktop:serve — reference desktop |
pnpm generate | Production build of reference desktop |
pnpm desktop | Control panel / CLI |
pnpm prepare:stubs | Stub-build kits, apps, themes |
pnpm prepare:modules | Stubs + dev:prepare on packages/apps/themes |
pnpm prepare:apps | dev:prepare for apps/* |
pnpm prepare:themes | dev:prepare for themes/* |
pnpm template:sync | desktop template |
pnpm validate:modules | desktop validate |
packageManager fieldnuxt.config.ts → modules: ['@owdproject/core']desktop.config.ts beside the Nuxt rootManual install (no CLI): add the package with pnpm/npm, then edit desktop.config.ts — see Package linking.