Seed Project

Overview

The io.Connect CLI is available via the @interopio/iocd-cli library, which provides various commands for creating and managing a seed project for io.Connect Desktop.

To install the library, execute the following command:

npm install -g @interopio/iocd-cli@latest

You can also use npx to directly execute package commands without global installation of the package:

npx @interopio/iocd-cli@latest create

Some of the commands are defined under the "scripts" property of the generated seed project package.json file and can be executed via npm:

Script Description
npm run apps-dev Invokes iocd apps dev.
npm run build Invokes iocd build.
npm run build-skip-install Invokes iocd build --skip-install.
npm run components-install Invokes iocd components install.
npm run dev Invokes iocd dev.
npm run setup Invokes iocd setup.
npm test Invokes iocd test.

Compatibility Checks

Available since @interopio/iocd-cli 2.0.0

The CLI checks the Node.js version, the seed project declarations and installed versions of supported build dependencies before running command actions. Successful checks produce no extra output. Problems include repair instructions and block only commands that require the incompatible dependency - e.g., an incompatible Forge version blocks iocd build, while iocd dev can continue with compatibility advice. An unsupported Node.js version blocks command actions.

Use iocd doctor to see the complete report. These checks read package metadata without evaluating config/forge.config.js, importing project dependency code, or changing project files. The doctor and help commands remain available when the project build dependencies or configuration are broken, provided the CLI itself can start.

Upgrading

As of @interopio/iocd-cli 2.0, the CLI requires Node.js 22.13.0 or later and Electron Forge 8. Updating only @interopio/iocd-cli in a seed created with an earlier version can leave incompatible Forge 7 dependencies. Upgrade the seed project build dependencies together:

  1. Upgrade Node.js on development machines and CI runners to v22.13.0 or later. Update the seed project package.json so that engines.node is ">=22.13.0", or a narrower range within the supported versions.

  2. From the seed root, inspect the project using the released CLI. This also works when the installed CLI doesn't have a doctor command:

npx @interopio/iocd-cli@latest doctor

The npx invocation may download the CLI to its cache. The doctor command itself doesn't modify the seed. A compatibility error is expected if the project still has older dependencies.

  1. Review and apply the install command suggested by the report. Update @interopio/iocd-cli to the latest version and align @electron-forge/core and the makers, publishers, and plugins already used by your seed with ^8.0.1. You don't need to add unused makers or publishers. For packages declared under optionalDependencies or using custom sources, follow the instructions in the report to preserve those declarations before running npm install.

  2. Review and commit both package.json and the updated package-lock.json, then verify the installed dependencies:

npx iocd doctor

The checks don't install dependencies or fix files automatically, and can't repair a failed npm install. If installation fails, correct the Node.js version and dependency declarations first.

Existing config/forge.config.js maker and publisher settings can be retained. If the file contains the postMake hook from templates generated before @interopio/iocd-cli 2.0 solely to write makeResults.json, that hook is no longer needed. As of 2.0, the CLI uses the make results from Forge 8 to sign the produced artifacts and publish those same files without rebuilding them.

Commands

The io.Connect CLI offers the following main commands:

Command Description
apps Command with sub-commands for managing the customizable system apps in the seed project.
build [options] Builds and packages the io.Connect Desktop platform for distribution.
components Command with sub-commands for managing the seed project components.
create [options] Creates a new seed project. Accepts options for configuring the seed project.
dev [options] Starts io.Connect Desktop in development mode (the platform isn't packaged yet).
doctor [options] Checks project compatibility and suggests fixes without changing project files. Available since @interopio/iocd-cli 2.0.0.
help [command] Displays help for the specified command.
license Displays current license key information.
modifications Command with sub-commands for managing the seed project modifications.
setup Prepares the seed project for first use by installing the configured components and the dependencies of all customizable system apps.
skills Command with sub-commands for managing the Agent Skills in the seed project. Available since @interopio/iocd-cli 1.1.0.
test Runs the test suite.

apps

The apps command has the following sub-commands:

Command Description
add <appName> Adds a new template app from the registry.
build [options] Builds all template apps and copies their output to the modifications folder. Requires installing the app dependencies first.
dev [options] Starts all template apps in development mode and copies their development modifications.
help [command] Displays help for the specified command.
install [options] Installs the dependencies of all template apps.
list Lists the template apps added to the seed project and all available templates.
update <appName> [--yes] Replaces an app with the template supplied by the CLI. Removes customizations after confirmation, unless --yes is supplied (see Updating a Template). Available since @interopio/iocd-cli 1.1.0.

build

The build command accepts the following options:

Option Description
-h, --help Displays help for the command.
--output <path> Output directory for packages, relative to the project root. If omitted, packages remain under /dist/make.
--publish-only Skips component installation, app builds, modifications, and initial signing. Also creates packages with Forge before publishing (see Build Commands). Defaults to false.
--skip-install Skips installing the components during the build. Defaults to false.

components

The components command has the following sub-commands:

Command Description
browse Lists all components available in the selected component store.
download [options] [output-dir] Downloads components from the current store to a local directory in local store format. By default, the latest version of each component is downloaded.
help [command] Displays help for the specified command.
install [name] Installs all components listed in iocd.cli.config.json, or a specific component by name. Installing a specific component saves its installed version in the configuration.
list Lists the components and versions configured in iocd.cli.config.json.
pin Pins all "latest" component versions to their current specific versions for reproducible builds.
uninstall <name> Removes a component from the project.

The components download command accepts the following options:

Option Description
-c, --components <list> Semicolon-separated list of components to download, optionally with versions (e.g., "iocd@10.0.3;devTools@latest"). Available since @interopio/iocd-cli 0.0.84.
-f, --force Overwrites existing files without prompting.
-h, --help Displays help for the command.

create

The create command accepts the following options:

Option Description
--applications <applications> Comma-separated list of apps (e.g., "groups,workspaces").
--components <components> Comma-separated list of components (e.g., "iocd,demos,devTools").
--folder-name <name> Folder name for non-interactive mode.
-h, --help Displays help for the command.
--license-key <key> License key for non-interactive mode. Required unless IOCD_LICENSE_KEY is set or config/iocd.license.key exists.
--non-interactive Runs the command in non-interactive mode using the provided options.
--product-name <name> Product name for non-interactive mode.
--source <url/path> Overrides the component source during setup.
--use-current-folder Creates the seed project in the current folder in non-interactive mode.

dev

The dev command accepts the following options:

Option Description
--extraLaunchArgs <arguments> Extra launch arguments passed to the io.Connect Desktop executable. The arguments are split by space.
-h, --help Displays help for the command.

doctor

Available since @interopio/iocd-cli 2.0.0

Run doctor from the seed root to check the project against the CLI being executed:

npx iocd doctor

This check works offline and reports the Node.js version, declared and installed Forge dependencies, and suggested repair commands. It exits with a non-zero status when compatibility errors are found. Warnings alone don't cause failure.

To check compatibility with a published CLI version or NPM tag before upgrading, use --target:

npx iocd doctor --target 2.1.0
npx iocd doctor --target latest

The target check uses the requirements published by the selected release without installing that release into the seed. It requires network access or unexpired cached release metadata. If metadata can't be obtained, the command fails rather than reporting the target as compatible. Omit --target to check the CLI being executed offline. The target release must publish compatibility metadata. CLI installations without doctor can use the temporary npx invocation described in Upgrading.

Option Description
-h, --help Displays help for the command.
--target <version-or-tag> Checks against a published CLI version or NPM tag, such as 2.1.0 or latest.

modifications

The modifications command has the following sub-commands:

Command Description
apply [component] Applies all modifications for the selected mode. The optional component argument is currently reserved and component-specific apply isn't implemented.
help [command] Displays help for the specified command.

The modifications apply command accepts the following options:

Option Description
-h, --help Displays help for the command.
--mode <mode> Mode to apply modifications for: dev or build. Defaults to dev.

skills

The skills command has the following sub-command:

Command Description
update Safely replaces all Agent Skills shipped by the CLI with their current versions. Preserves unrelated skills and restores or retains the previous skill if publishing a replacement fails.

test

The test command runs the configured test suite. It also provides the following sub-command:

Command Description
setup Creates and validates the current automated test infrastructure when the configured test directory is missing. Refuses to overwrite an existing directory. Available since @interopio/iocd-cli 1.0.0.