npm package: @itwin/extension-cli
Description: A CLI tool for viewing, creating, and updating iTwin.js Extensions and Extension Versions from the iTwin.js Extension Service
Author: Bentley Systems, Inc.
Latest version: 0.6.0

# @itwin/extension-cli

Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.

Allows convenient viewing, downloading and publishing iTwin.js Extensions and Extension Versions from the iTwin.js Extension Service

## Usage

`node extension-cli <command> <options>`

- `command` must be one of the following:
  - `get-extensions` - Gets extensions for a given iTwinId
  - `get-extension-versions` - Shows all versions of a specific extension
  - `get-extension-version` - Shows metadata for a specific extension version
  - `get-latest-extension-version` - Shows metadata for the latest extension version
  - `publish-extension` - Publishes a new extension
  - `publish-extension-version` - Publishes a new extension version
  - `update-extension` - Updates the properties of an extension
  - `download` - Downloads an extension
- `options` described in section below.

## Command options

### `get-extensions`

- `--iTwinId` (`--itwin`) - specific iTwinId for which extensions are retrieved

### `get-extension-versions`

- `--extensionId` (`--extension`) - extensionId for the desired extension

### `get-extension-version`

- `--extensionId` (`--extension`) - extensionId for the desired extension
- `--extensionVersion` (`--extension-version`) - specific version number of the extension for which the metadata should be retrieved

### `get-latest-extension-version`

- `--extensionId` (`--extension`) - extensionId for the desired extension
- `--iTwinJsVersion` (`--itwinjs-version`) - [Optional] specific iTwin.js version used to filter supported versions

### `publish-extension`

- `--name` - name of the new extension being published
- `--description` (`--desc`) - [Optional] description for the new extension
- `--iTwinId` (`--itwin`) - the account iTwinId where the extension should be scoped

### `publish-extension-version`

- `--extensionId` (`--extension`) - id of the extension for which the new version is being published
- `--filePath` (`--path`) - path to extension package.json file.

### `update-extension`

- `--extensionId` (`--extension`) - id of the extension which is being updated
- `--description` (`--desc`) - [Optional] the new description for the extension (not providing a new description will delete extension description)

### `download`

- `--extensionId` (`--extension`) - id of the extension to downloaded
- `--extensionVersion` (`--extension-version`) - number of the version to downloaded
- `--savePath` (`--path`) - path to where the extension should be downloaded
- `--clean` - [Optional] will delete any existing files in the save path

### Examples

| Action | Command |
|-|-|
| Get extensions for a specific iTwin | `extension-cli get-extensions --iTwinId 00000000-0000-0000-0000-000000000000` |
| Get all versions for a specific extension | `extension-cli get-extension-versions --extension 00000000-0000-0000-0000-000000000000` |
| Get metadata for a specific extension version | `extension-cli get-extension-version --extension 00000000-0000-0000-0000-000000000000 --extension-version 1.0.0` |
| Get metadata for the latest extension version | `extension-cli get-latest-extension-version --extension 00000000-0000-0000-0000-000000000000` |
| Publish a new extension on an account iTwin | `extension-cli publish-extension --name newExtension --description "My new extension" --itwin 00000000-0000-0000-0000-000000000000` |
| Publish a new extension version | `extension-cli publish-extension-version --extensionId 00000000-0000-0000-0000-000000000000 --filePath /path/to/package.json` |
| Update the description of an extension | `extension-cli update-extension --desc "My new description" --extensionId 00000000-0000-0000-0000-000000000000` |
| Download an extension to a local folder | `extension-cli download --extension 00000000-0000-0000-0000-000000000000 --extension-version 1.0.0 --path ./temp` |

## Uploading extension

Before starting, extensions can only be associated with an account iTwin so make sure you have access to your organization account iTwin and have `ManageExtensions` RBAC permission on that iTwin.

Firstly, extension needs to be created using [publish-extension](#publish-extension). `iTwinId` must be an ID of your organization account iTwin. Extensions and all its versions will be available to any users what have access to any iTwin under your provided account iTwin. After running command you'll see extension ID, this will be used to uniquely identify your extension among every other extension.

Finally, to upload extension version you'll need to use [publish-extension-version](#publish-extension-version) command. `extensionId` is your extension id and `filePath` should be a path to the manifest (_package.json_) file. Before trying to upload extension version make sure that your manifest satisfies these requirements:
- `name` property matches your extension name.
- `version` property exists with a valid semantic versioning number.
- `main` property contains path to JavaScript file.
- Has dependency or peer dependency on `@itwin/core-extension` package.

For more information, see [iTwin.js Extensions documentation](https://www.itwinjs.org/learning/frontend/extensions/).

At the moment, CLI doesn't provide delete functionality. If publishing of extension version failed, you may need to bump extension version in manifest file before trying again.