Dimo

plugin

npx dimo plugin packs a deterministic .vxp and installs, lists, updates, uninstalls, and publishes packages on the current Host and the official marketplace. Templates and harness tests use dimo-plugin (source at packages/plugin-cli). Bind a Host with dimo plugin run server, then dimo plugin run dev from the plugin directory. See Development workflow.

When desktop or npx dimo serve is running, the command finds the local Host token. If no Host is up, add writes snapshots to ~/.dimo/imports/ and linked directories to ~/.dimo/imports/links.jsonl; the next launch imports them. Default URL is http://127.0.0.1:17891; override with DIMO_URL / DIMO_TOKEN. list, update, remove, gc-runtimes, and test --host need a running Host.

npx dimo plugin pack

bash
npx dimo plugin pack
npx dimo plugin pack .
npx dimo plugin pack ./my-plugin
npx dimo plugin pack ./my-plugin --output ./dist/office.vxp

The first argument is the plugin root; it defaults to the current directory. That directory must contain .dimo-plugin/plugin.json, README.md, and the rest of the layout in Package layout.

Order of work: full validation first (summary, schema, content index, integration refs). Failures print each code: message line and exit. On success a .vxp is written and stdout prints two lines:

text
/absolute/path/dist/<plugin-id>-<version>.vxp
sha256:<packageDigest>

--output sets the result file. The default is dist/<plugin-id>-<version>.vxp inside the plugin directory.

The same source packed twice with npx dimo plugin pack should yield the same sha256. Published npx packages embed plugin-cli under plugin-cli/. A missing directory raises Dimo Plugin CLI is unavailable; reinstall or upgrade the dimo npm package.

npx dimo plugin add

bash
npx dimo plugin add --web <git-or-url[#ref]> [--plugin ID] [--yes]
npx dimo plugin add --profile <file.vxp|archive> [--plugin ID] [--yes]
npx dimo plugin add --dev <dir> [--yes] [--detach]

--web accepts a marketplace page, Git repository, GitHub Release, or archive URL. #tag, #branch, and #commit pin the tree. A GitHub Release that ships a .vxp verifies SHA-256 when a digest or sibling .sha256 is present. --profile installs a local archive. --dev links a development directory: it builds first, then the Host watches the digest; without --detach it prints Worker stderr; --detach returns after linking. HMR is started by dimo plugin run dev. Use only one of the three modes. Without a flag, the command infers directory, file, or URL.

Add --plugin when the archive contains more than one package. Use --yes when stdin is not a TTY.

User path: Install a Plugin from the marketplace. Linked development: Development workflow.

npx dimo plugin list / update / remove

bash
npx dimo plugin list [--json]
npx dimo plugin update <id> [--ref tag] [--yes]
npx dimo plugin remove <id> [--yes] [--delete-data]
npx dimo plugin gc-runtimes

list is the Installed catalog, including source and lock. update fetches another snapshot from the locked origin; linked development plugins edit the source directory instead. remove uninstalls an installed package and keeps config by default; --delete-data deletes the Host-managed snapshot and config, and reclaims unreferenced Runtimes. A linked development directory is not deleted. gc-runtimes deletes Host-managed Runtimes that no plugin references.

Unknown subcommands such as npx dimo plugin init raise Unknown plugin command. Init belongs to dimo-plugin.

npx dimo plugin publish

bash
npx dimo plugin publish [dir|file.vxp]
npx dimo plugin publish --web <github-owner/repo[#tag]>

Submit a packed package or a GitHub repository into the official marketplace review queue. Register a marketplace account first. The GitHub owner must match the marketplace username.

Credentials come from --owner / --password, or DIMO_MARKET_OWNER / DIMO_MARKET_PASSWORD. The default catalog is https://dimo-ai.com; override with DIMO_MARKETPLACE_URL. Packed uploads can pass --show-tree to show the package tree; GitHub listings show it by default.

After review, one owner/plugin-name card keeps version history. A listed GitHub repository adds a version when a new tag is pushed and keeps older versions. Hosts that installed from that card or repository show an update affordance.

npx dimo plugin test --host

bash
npx dimo plugin test --host
npx dimo plugin test --host ./my-plugin

Runs link, enable, chrome / structure contribution appear-and-withdraw, Skill reload, and uninstall against a running Host. Looks up a local Host token when DIMO_TOKEN is unset.

npx dimo plugin --help / npx dimo help plugin

bash
npx dimo plugin --help
npx dimo help plugin

Prints usage for pack / add / publish / list / update / remove / gc-runtimes / test --host / run and skips the Host.

Environment and troubleshooting

Variables read when starting the Host

These apply when running npx dimo or npx dimo serve.

DIMO_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.

DIMO_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/DimoADE/Dimo/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.

DIMO_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, dimo-server, web/). When set, download is skipped.

DIMO_GITHUB_REPO: GitHub owner/name, default DimoADE/Dimo.

DIMO_STATIC_ROOT: Web UI static file root. npx dimo points it at packaged web/. When you start dimo-server yourself and need the browser UI, point this at a web/ tree.

DIMO_SERVER_ALLOW_LAN: set to 1 and even npx dimo (loopback start) listens on every NIC. npx dimo serve --local on the command line still binds loopback only.

DIMO_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.

DIMO_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.

DIMO_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.

DIMO_DATA_DIR: Host data directory. npx dimo serve, npx dimo list, and npx dimo install share this SQLite. Unset, the machine default data directory is used.

Variables read by control commands

DIMO_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.

DIMO_TOKEN: Bearer token, required. Missing it raises DIMO_TOKEN is required. Copy it from the Token block of npx dimo serve, or from desktop Settings → Remote connection.

Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.

Common failures

Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.

Host family download failed: network, firewall, or a bad tag. Check DIMO_HOST_FAMILY_TAG and open the Release page for dimo-host-family-<platform>.tar.gz.

Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.dimo/host-family/<tag>/ and retry, or point at a verified DIMO_HOST_FAMILY_DIR.

Host family is missing dimo-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.

DIMO_TOKEN is required: the token is unset. Run npx dimo serve and copy from the terminal, or copy from the desktop remote-connection page.

Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx dimo conversation show / npx dimo workflow show.

Missing required --x: a required flag is absent. Compare with npx dimo help conversation (or the matching resource).

Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx dimo plugin pack again.

Port in use: switch to npx dimo serve --port 18080, or stop the process holding 17891.

pass --yes to install without a prompt: npx dimo install ran without a terminal and without --yes. Use npx dimo install AGENT_ID --yes.

npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx dimo install. Full write-up: Install Agents locally.

bash
npx dimo help
npx dimo --version