The wamp CLI

The wamp CLI is the public extension-authoring surface. It works in the directory you choose; an extension does not have to live in the WAMP source tree or inside the desktop profile.

wamp ext init my-extension --template full
cd my-extension
wamp ext dev

The SDK package contains the CLI, compiler, public type declarations, WAMP UI styles and both starter templates. Ordinary npm dependencies are optional: add a package.json yourself when you need one. The build bundles those dependencies into the extension artifacts.

Commands

Command	What it does
wamp ext init [path]	Creates and builds an extension project. The path defaults to the current directory and must be empty.
wamp ext dev [path]	Builds, links into the selected WAMP desktop profile, then rebuilds on source changes.
wamp ext pack [path]	Rebuilds, validates and writes an installable ZIP.
wamp ext install [path]	Builds and packs a WAMP project, archives a portable plugin directory as-is, or sends a ZIP unchanged to the running WAMP.
wamp ext status [path]	Reports what the running WAMP did with the extension: loaded, active or faulted.

Every command accepts --json. dev emits newline-delimited ready, failed, and stopped records, which makes the same commands usable by humans and coding agents. Extension authoring needs no CLI login: the CLI only reads and writes local files. Account, organization, app registration and publishing remain authenticated product operations.

wamp ext init

wamp ext init [path] [--template minimal|full] [--no-build] [--json]

minimal creates a page, renderer entry and activation entry. full adds a typed data schema, notification, extension tool and scoped AI session. Both use only public imports: @wamp/extension-sdk, @wamp/plugin-api, and @wamp/ui.

The target directory name becomes the extension id. init . therefore turns an empty current workspace into the project instead of creating an unrelated nested directory. The scaffold has no package.json and does not run npm install. Add a package.json later if the extension needs ordinary npm dependencies; the builder bundles them. --no-build writes the files and skips the first compile.

wamp ext dev

wamp ext dev [path] [--user-data-dir path] [--json]

dev performs a complete build before linking anything. It uses the platform’s standard desktop profile by default, or the explicit profile passed through --user-data-dir, and creates <profile>/extensions/dynamic/<extension-id> as a symlink to the workspace. The running host discovers and reloads that link while the CLI’s matching owner lease is live. An unowned, expired, revoked, or target-mismatched link is ignored and an installed copy of the same extension id loads instead.

On each source change the CLI validates and builds into a temporary directory, then atomically replaces dist/. A failed edit reports diagnostics while the last good extension stays loaded. On shutdown the CLI revokes its lease without deleting the shared symlink path; this prevents an old process from deleting a successor’s link. The next run safely replaces revoked, expired, or legacy unowned symlink residue, including a link to another project. It refuses to replace a real directory or a link with another live owner.

If the project has build.mjs, dev runs it and validates the resulting public artifact contract. Otherwise it calls the SDK builder directly.

wamp ext pack

wamp ext pack [path] [--output file] [--json]

The default output is release/<extension-id>-<manifest-version>.zip. Packing runs the build again, checks extension.json, declared runtime artifacts and public import boundaries, then includes only the installable surface:

• extension.json and sanitized package metadata;
• dist/, icons, assets, native modules and runtime launchers;
• agents, tools and skills;
• license and notice files.

Source, tests, credentials, editor state and node_modules are excluded. A symlink anywhere in a packaged tree is rejected instead of being followed. A declared main or server entrypoint, and every file a manifest value names as ${extensionDir}/<path>, must be in the archive, or pack fails naming it. A server you write yourself belongs under runtime/: the build replaces dist/.

The output names the archive’s sha256 (sha256 with --json), the digest a WAMP Cloud environment lists the archive by. digest with --json is the build’s, which dev and status compare.

wamp ext install

wamp ext install [path] [--output file] [--json]

For a WAMP project, install runs pack. A portable plugin directory is archived as-is under its directory name; a .zip is sent unchanged. Run the command from a WAMP terminal or agent shell so it can reach the running engine. WAMP validates the archive before publishing an installed copy at <profile>/extensions/imported/<extension-id>, the same copy Install from file creates. It stays after dev stops and across restarts. A plugin update replaces that copy only when the source format and original plugin name match.

For WAMP projects the id is the project directory name recorded in the archive. For plugins it is derived from the original plugin name; the archive comment cannot change it. WAMP refuses an id that a built-in, Marketplace, or different imported package already holds and leaves that copy untouched.

While dev runs, its link of the same id is the copy that loads. install still writes the installed copy, then exits 4 and says to stop dev.

The archive travels in one message and may be at most about 47 MiB.

A WAMP Cloud sandbox has no running engine to install into; there an extension belongs to the session’s environment. With no engine to reach, install exits 3 and its message names the Cloud route with the archive’s digest: present the .zip, then add it with the platform tool’s environments.archives.put and list it in the environment’s extensions.

A WAMP shell may reach the headless core rather than Desktop. Desktop also runs an Electron-side loader that the command cannot ask; the output says so when that applies.

Supported extension surface

The public builder handles the same shapes used by shipped extensions: renderer pages and views, Electron main, headless server, extension services, tools, typed data, AI sessions, cron and notifications, agents, skills, runtime launchers, assets and native payloads. Manifest build.loaders rules and ordinary npm imports are bundled without a WAMP checkout.

Imports from WAMP’s source aliases or paths outside the extension root are build errors. If a shipped extension needs such an import, its capability belongs in the public SDK first; the repository guard prevents first-party code from silently relying on a private escape hatch.

Exit codes

Code	Meaning
0	Command completed, or dev stopped cleanly.
1	Build, validation, watch or filesystem operation failed, or WAMP refused, failed or faulted the install.
2	Invalid command, flag, path or template.
3	status or install could not reach a running WAMP. Outside a WAMP shell the message names the missing variable; inside a network-disabled Codex sandbox it says to rerun with escalated permissions.
4	install wrote the installed copy, but a development copy of the same id is the one loaded.

See the manifest reference, Plugin API, and Packages and SDKs for the contracts used by the CLI.