@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. 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 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.

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.