# CLI

Source: https://docs.interop.io/desktop/developers/seed-project/cli/index.html

## Overview

The io.Connect CLI is available via the [`@interopio/iocd-cli`](https://www.npmjs.com/package/@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:

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

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

```cmd
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`](#commands-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:

```cmd
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.

3. 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`.

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

```cmd
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](https://docs.interop.io/desktop/developers/seed-project/apps/index.md#using_template_apps-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](https://docs.interop.io/desktop/developers/seed-project/building-for-production/index.md#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:

```cmd
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`:

```cmd
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](#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.* |