@itwin/workspace-editor 4.0.0-dev.90 → 4.0.0-dev.92

package/package.json

@@ -2,7 +2,7 @@
   "name": "@itwin/workspace-editor",
   "license": "MIT",
   "main": "lib/WorkspaceEditor.js",
-  "version": "4.0.0-dev.90",
+  "version": "4.0.0-dev.92",
   "bin": {
     "WorkspaceEditor": "./lib/WorkspaceEditor.js"
   },
@@ -15,14 +15,13 @@
     "directory": "utils/workspace-editor"
   },
   "dependencies": {
-    "@itwin/core-bentley": "4.0.0-dev.90",
-    "@itwin/core-common": "4.0.0-dev.90",
-    "@itwin/core-backend": "4.0.0-dev.90",
     "glob": "^7.1.2",
-    "yargs": "^17.4.0"
+    "yargs": "^17.4.0",
+    "@itwin/core-bentley": "4.0.0-dev.92",
+    "@itwin/core-common": "4.0.0-dev.92",
+    "@itwin/core-backend": "4.0.0-dev.92"
   },
   "devDependencies": {
-    "@itwin/build-tools": "4.0.0-dev.90",
     "@itwin/eslint-plugin": "^4.0.0-dev.33",
     "@types/chai": "4.3.1",
     "@types/mocha": "^8.2.2",
@@ -31,7 +30,8 @@
     "eslint": "^8.36.0",
     "mocha": "^10.0.0",
     "rimraf": "^3.0.2",
-    "typescript": "~5.0.2"
+    "typescript": "~5.0.2",
+    "@itwin/build-tools": "4.0.0-dev.92"
   },
   "eslintConfig": {
     "plugins": [
@@ -46,6 +46,5 @@
     "docs": "",
     "lint": "eslint -f visualstudio \"./src/**/*.ts\" 1>&2",
     "test": ""
-  },
-  "readme": "# WorkspaceEditor\r\n\r\n**WorkspaceEditor** is a command line utility for creating and editing `WorkspaceResources` in iTwin `WorkspaceDb`s, and for uploading, downloading, and editing `WorkspaceDb`s in cloud `WorkspaceContainer`s.\r\n\r\nAn iTwin `WorkspaceDb` may hold many `WorkSpaceResources`, each with a `WorkspaceResource.Name` and type. `WorkspaceEditor` adds, updates, deletes, and extracts *local files* into/from a `WorkspaceDb`.\r\n\r\n## Workspace Resource Types\r\n\r\nThere are 3 `WorkspaceResourceType`s that may be accessed by `@itwin-backend` applications at runtime via the `WorkspaceDb` api:\r\n\r\n 1. `string` accessed via the `getString` method\r\n 2. `blob`  binary data accessed via the `getBlob` method\r\n 3. `file`  extracted to a local file via the `getFile` method\r\n\r\nSeveral `WorkspaceEditor` commands require a `--type` argument to specify which `WorkspaceResourceType` to use.\r\n\r\n## The WorkspaceContainer Directory\r\n\r\n`WorkspaceDb`s may be either local files or from cloud `WorkspaceContainers`. When creating new `WorkspaceDb`s, it is sometimes useful to just work with a local file until all resources have been imported, before uploading the WorkspaceDb to the cloud container.\r\n\r\n`WorkspaceDb`s are located by iTwin.js inside a `WorkspaceContainer` subdirectory within the `WorkspaceContainerDir` directory. `WorkspaceContainerDir` is specified as a directory name in the `workspace.containerDir` member on the `configuration` argument of  `IModelHost.startup`. The default value is `%localappdata%/iTwin/Workspace`.\r\n\r\nWorkspaceEditor will normally create and edit `WorkspaceDb`s in the default directory, but if you wish to use a different directory, supply the `--directory` option to specify a different `WorkspaceContainerDir` location.\r\n\r\n## Workspace dbName\r\n\r\nThe WorkspaceEditor commands all take a `dbName` option to specify the `WorkspaceDb` on which to operate. The WorkspaceDb is located inside the `WorkspaceContainer` specified with the --containerId argument. `WorkspaceDbName`s must be less than 255 characters, may not have leading or trailing whitespace, and may not use any reserved path specification characters (see documentation for `WorkspaceDbName` for details.) The `WorkspaceDb` filename is formed via: `${WorkspaceContainerDir}/${WorkspaceContainerId}/${WorkspaceDbName}.itwin-workspace`.\r\n\r\n## WorkspaceEditor Config file\r\n\r\n`WorkspaceEditor` accepts the `--config` option to specify the name of a JSON file that holds values for `WorkspaceEditor` options. By default, `WorkspaceEditor` looks in the current directory for a file named `workspaceEditor.json`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor --config myConfig.json listDb db1\r\n...\r\n```\r\n\r\n```json\r\nmyConfig.json:\r\n\r\n{\r\n  \"containerId\": \"5d385232-a2ec-4f31-b74b-8201c027848d\",\r\n  \"accessName\": \"smsblob1\",\r\n  \"storageType\": \"azure?sas=1\",\r\n  \"user\": \"workspace editor example\",\r\n  \"accessToken\": \"<valid token here>\"\r\n}\r\n```\r\n\r\n> config files *must* have a `.json` extension.\r\n\r\n## WORKSPACE_EDITOR_xxx Environment Variables\r\n\r\nAny command line option may also be specified by setting a shell environment variable with the option's name after the prefix `WORKSPACE_EDITOR_`.\r\n\r\nFor example, config files may also be specified by setting the environment variable `WORKSPACE_EDITOR_CONFIG`.\r\n\r\n```cmd\r\nset WORKSPACE_EDITOR_CONFIG=d:\\projData\\config.json\r\n```\r\n\r\nTo specify camelCase options, separate the words with an underbar, e.g.:\r\n\r\n```cmd\r\nset WORKSPACE_EDITOR_ACCESS_TOKEN=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==\r\n```\r\n\r\n> `WORKSPACE_EDITOR_` environment variable names are *case sensitive* and must be ALL CAPS\r\n\r\n## WorkspaceEditor Commands\r\n\r\nThe following WorkspaceEditor commands are available:\r\n\r\n```sh\r\n> WorkspaceEditor\r\n\r\nEdits or lists contents of a WorkspaceDb\r\n\r\nCommands:\r\n  WorkspaceEditor add <dbName> <files>                   add files into a WorkspaceDb\r\n  WorkspaceEditor replace <dbName> <files>               replace files in a WorkspaceDb\r\n  WorkspaceEditor remove <dbName> <rscName>              remove a resource from a WorkspaceDb\r\n  WorkspaceEditor extract <dbName> <rscName> <fileName>  extract a resource from a WorkspaceDb into a local file\r\n  WorkspaceEditor listDb <dbName>                        list the contents of a WorkspaceDb\r\n  WorkspaceEditor deleteDb <dbName>                      delete a WorkspaceDb from a cloud container\r\n  WorkspaceEditor createDb <dbName>                      create a new WorkspaceDb\r\n  WorkspaceEditor copyDb <dbName> <newDbName>            make a copy of a WorkspaceDb in a cloud container with a new name\r\n  WorkspaceEditor versionDb <dbName>                     make a new version of a WorkspaceDb\r\n  WorkspaceEditor vacuumDb <dbName>                      vacuum a WorkspaceDb\r\n  WorkspaceEditor importDb <dbName> <localFileName>      import a WorkspaceDb into a cloud container\r\n  WorkspaceEditor exportDb <dbName> <localFileName>      export a WorkspaceDb from a cloud container to a local file\r\n  WorkspaceEditor queryDbs [like]                        query the list of WorkspaceDbs in a cloud container\r\n  WorkspaceEditor acquireLock                            acquire the write lock for a cloud container\r\n  WorkspaceEditor releaseLock                            release the write lock for a cloud container\r\n  WorkspaceEditor clearWriteLock                         clear the write lock for a cloud container. Note: this can be dangerous!\r\n  WorkspaceEditor purgeWorkspace                         purge deleted blocks from a WorkspaceContainer\r\n  WorkspaceEditor initializeWorkspace                    initialize a WorkspaceContainer (empties if already initialized)\r\n```\r\n\r\n## Commands that operate on WorkspaceDbs\r\n\r\nAll of the examples in this section use `local.json` for config:\r\n\r\n```\r\nset WORKSPACE_EDITOR_CONFIG=r:\\local.json\r\n```\r\n\r\n```json\r\nr:\\local.json:\r\n{\r\n  \"directory\": \"r:/workspaces\",\r\n  \"containerId\": \"proj112\"\r\n}\r\n```\r\n\r\nThe name of the `WorkspaceDb` is supplied with the `dbName` argument. For cloud-based `WorkspaceContainers`, `dbName` may either include the version number (e.g. `pipe-spec:1.3.2`) or, if no version is supplied, the highest version is used.\r\n\r\n### createDb \\<dbName>\r\n\r\nCreate a new empty `WorkspaceDb`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor createDb proj\r\ncreated WorkspaceDb r:\\workspaces\\proj112\\proj.itwin-workspace\r\n```\r\n\r\n### add \\<dbName> \\<files>\r\n\r\nAdd one or more local files as resources into a `WorkspaceDb`.\r\n\r\n`--rscName` specifies the name of the resource. Defaults to the name of the local file.\r\n`--root` specifies a root directory when adding multiple files. The parts of the path after the root are saved in the resource name (see example below.)\r\n`--type` specifies the type of resource(s) to add. Required\r\n\r\n> Note: `--rscName`  is only applicable when adding a single file.\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor add proj --rscName=equipment-data --type=file r:\\data\\equip.dat\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:/data/equip.dat\" as file resource [equipment-data]\r\n\r\n> WorkspaceEditor add proj --type=string --root=r:\\json *\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:\\json\\contracts.json\" as string resource [contracts.json]\r\n added \"r:\\json\\firecode.json\" as string resource [firecode.json]\r\n added \"r:\\json\\specs.json\" as string resource [specs.json]\r\n added \"r:\\json\\vendor.json\" as string resource [vendor.json]\r\n\r\n > WorkspaceEditor add proj --type=blob --root=r:\\dict **\\*.dict\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:\\dict\\Sparks\\KDE05814.dict\" as blob resource [Sparks/KDE05814.dict]\r\n added \"r:\\dict\\Sparks\\KDE05815.dict\" as blob resource [Sparks/KDE05815.dict]\r\n added \"r:\\dict\\Sparks\\KDE05816.dict\" as blob resource [Sparks/KDE05816.dict]\r\n added \"r:\\dict\\Sparks\\KDE05922.dict\" as blob resource [Sparks/KDE05922.dict]\r\n added \"r:\\dict\\Sparks\\KDE05929.dict\" as blob resource [Sparks/KDE05929.dict]\r\n added \"r:\\dict\\TernKit\\TRN02324.dict\" as blob resource [TernKit/TRN02324.dict]\r\n added \"r:\\dict\\TernKit\\TRN05314.dict\" as blob resource [TernKit/TRN05314.dict]\r\n added \"r:\\dict\\TernKit\\TRN05814.dict\" as blob resource [TernKit/TRN05814.dict]\r\n added \"r:\\dict\\TernKit\\TRN09911.dict\" as blob resource [TernKit/TRN09911.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05554.dict\" as blob resource [UniSpace/KRT05554.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05800.dict\" as blob resource [UniSpace/KRT05800.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05814.dict\" as blob resource [UniSpace/KRT05814.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05820.dict\" as blob resource [UniSpace/KRT05820.dict]\r\n added \"r:\\dict\\UniSpace\\KRT06519.dict\" as blob resource [UniSpace/KRT06519.dict]\r\n```\r\n\r\n### replace \\<dbName> \\<files>\r\n\r\nReplace an existing resource in a `WorkspaceDb` with a new version.\r\n\r\nTakes the same arguments as `add`.\r\n\r\n### remove \\<dbName> \\<rscName>\r\n\r\nRemove an existing `WorkspaceResource` from a `WorkspaceDb`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor remove proj --type blob UniSpace/KRT06519.dict\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n removed blob resource [UniSpace/KRT06519.dict]\r\n```\r\n\r\n### extract \\<dbName> \\<rscName> \\<fileName>\r\n\r\nExtract a `WorkspaceResource` from a `WorkspaceDb` into a local file, leaving the `WorkspaceResource` unchanged in the `WorkspaceDb`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor extract proj -t blob UniSpace/KRT05820.dict d:\\temp\\kd.dict\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n blob resource [UniSpace/KRT05820.dict] extracted to \"d:\\temp\\kd.dict\"\r\n```\r\n\r\n### listDb \\<dbName>\r\n\r\nList the contents of a `WorkspaceDb`. By default it will show all 3 resource types. To limit the output to specific types, supply the `--strings`, `--blobs`, or `--files` options.\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor list proj\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n strings:\r\n  name=contracts.json, size=17K\r\n  name=firecode.json, size=3K\r\n  name=specs.json, size=8K\r\n  name=vendor.json, size=46K\r\n blobs:\r\n  name=Sparks/KDE05814.dict, size=224K\r\n  name=Sparks/KDE05815.dict, size=307K\r\n  name=Sparks/KDE05816.dict, size=32K\r\n  name=Sparks/KDE05922.dict, size=56K\r\n  name=Sparks/KDE05929.dict, size=15K\r\n  name=TernKit/TRN02324.dict, size=405\r\n  name=TernKit/TRN05314.dict, size=67K\r\n  name=TernKit/TRN05814.dict, size=7K\r\n  name=TernKit/TRN09911.dict, size=3K\r\n  name=UniSpace/KRT05554.dict, size=2K\r\n  name=UniSpace/KRT05800.dict, size=5K\r\n  name=UniSpace/KRT05814.dict, size=13K\r\n  name=UniSpace/KRT05820.dict, size=7K\r\n files:\r\n  name=equipment-data, size=134K, ext=\"dat\", date=Tue Jul 08 2021 13:55:19 GMT-0400 (Eastern Daylight Time)\r\n\r\n> WorkspaceEditor list proj --strings\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n strings:\r\n  name=contracts.json, size=17K\r\n  name=firecode.json, size=3K\r\n  name=specs.json, size=8K\r\n  name=vendor.json, size=46K\r\n```\r\n\r\n### vacuumDb\r\n\r\n[Vacuum](https://www.sqlite.org/lang_vacuum.html) a `WorkspaceDb`. This can make a `WorkspaceDb` smaller and more efficient to access.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor vacuumDb proj\r\nVacuuming r:\\workspaces\\proj112\\proj.itwin-workspace ... done\r\n```\r\n\r\n## Commands that operate on Cloud WorkspaceContainers\r\n\r\nThe following `WorkspaceEditor` commands work only on cloud-based `WorkspaceContainers`.\r\n\r\nAll of the examples in this section use `cloud.json` for config:\r\n\r\n```\r\nset WORKSPACE_EDITOR_CONFIG=r:\\cloud.json\r\n```\r\n\r\n```json\r\nr:\\cloud.json:\r\n{\r\n  \"directory\": \"r:/workspaces\",\r\n  \"accessName\": \"<storage account name here>\",\r\n  \"accessToken\": \"<storage account key here>\",\r\n  \"storageType\": \"azure?sas=0\",\r\n  \"containerId\": \"5d385232-a2ec-4f31-b74b-8201c027848d\",\r\n  \"user\": \"Example editor admin\"\r\n}\r\n```\r\n\r\nWhen operating on cloud `WorkspaceContainer`s, WorkspaceEditor must first [obtain the write lock](#acquirelock) on the container. If successful, the lock is held on the container and all changes are only made locally (i.e. not visible to users) until [the write lock is released](#releaselock). Only a single administrator may be editing a cloud WorkspaceContainer at a time. Most WorkspaceEditor commands will fail if the write lock is not held.\r\n\r\nThe normal workflow for changing a `WorkspaceDb` in a cloud `WorkspaceContainer` involves running WorkspaceEditor multiple times to:\r\n\r\n1. Acquire the write lock on the container using [acquireLock](#acquirelock)\r\n2. Create a new version (major, minor, or patch) of the `WorkspaceDb` using [versionDb](#versiondb-dbname)\r\n3. Edit the new version using one or more [add](#add-dbname-files), [replace](#replace-dbname-files), or [remove](#remove-dbname-rscname) resource commands.\r\n4. Release the write lock using [releaselock](#releaselock)\r\n\r\n### initializeWorkspace\r\n\r\nInitialize or empty the contents of a cloud `WorkspaceContainer`. This command should be used after a cloud storage container is first created, or to empty an existing previously-initialized storage container.\r\n\r\nSince this command will destroy any existing contents of the container, should be used with care. There is an `Are you sure...` prompt to avoid accidents. The `--noPrompt` option can be used from scripts.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor initializeWorkspace\r\nAre you sure you want to initialize container [5d385232-a2ec-4f31-b74b-8201c027848d]\"? [y/n]: y\r\ncontainer \"5d385232-a2ec-4f31-b74b-8201c027848d initialized\r\n\r\n -or-\r\n\r\n> WorkspaceEditor initializeWorkspace --noPrompt\r\ncontainer \"5d385232-a2ec-4f31-b74b-8201c027848d initialized\r\n```\r\n\r\n### acquireLock\r\n\r\nAttempt to acquire the write lock for the cloud `WorkspaceContainer`. This command places the value of the `--user` argument in the lock state of cloud container, so if another user attempts to acquire the write lock before it is released, they will see an error message indicating that the lock is currently held and by whom.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor acquireLock\r\nacquired lock for container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n```\r\n\r\n> While the write lock is held, all changes to the `WorkspaceContainer` are stored locally and cannot be seen by users until the lock is released.\r\n\r\n> The write lock expires after one hour and may thereafter be acquired by others. If no other editor has acquired the lock, it may be re-acquired. However, if someone else acquires the lock, all local changes are lost and must be abandoned.\r\n\r\n### releaseLock\r\n\r\nAttempt to upload any local changes to the cloud `WorkspaceContainer` and, upon success, release the write lock.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor releaseLock\r\nreleased lock for container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n```\r\n\r\n### clearWriteLock\r\n\r\nClear the write lock currently held by another (failed) editor. This command \"steals\" the lock away from its current owner. After this command, the original holder of the write lock will fail when/if it attempts to release its lock and will lose all its changes.\r\n\r\n> This command is not normally ever needed, and should only be used in extreme cases when it is know to be safe.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor clearWriteLock\r\nwrite lock cleared for container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n```\r\n\r\n### importDb \\<dbName> \\<localFileName>\r\n\r\nImport a locally-created `WorkspaceDb` file into a cloud container. The first argument determines the name of the WorkspaceDb within the cloud container. If you don't supply an initial version number, in the form \":major.minor.patch\", it will be \"1.0.0\". The second argument is the name of the local file (without the \".itwin-workspace\" extension), including the local container name (since local container names often differ from cloud container names).\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor importDb project proj112\\proj\r\nVacuuming r:\\workspaces\\proj112\\proj.itwin-workspace ... done\r\nimport r:\\workspaces\\proj112\\proj.itwin-workspace, container=5d385232-a2ec-4f31-b74b-8201c027848d, dbName=project:1.0.0 : complete, 0.044 seconds\r\n\r\n- or -\r\n\r\n> WorkspaceEditor importDb project:2.0.2 proj112\\proj\r\nVacuuming r:\\workspaces\\proj112\\proj.itwin-workspace ... done\r\nimport r:\\workspaces\\proj112\\proj.itwin-workspace, container=5d385232-a2ec-4f31-b74b-8201c027848d, dbName=project:2.0.2 : complete, 0.044 seconds\r\n```\r\n\r\n### versionDb \\<dbName>\r\n\r\nCreate a new version of an existing WorkspaceDb so it may be edited. All of the resource editing commands will only work after the `versionDb` command and before the `releaseLock` command.\r\n\r\nAfter creating a new version of a WorkspaceDb, you must release the write lock for the new version to be visible to users. After the write lock is released on a version of a `WorkspaceDb` **it becomes immutable** and may never be modified again.\r\n\r\n`dBName` indicates the source database from which the new version is created. `dbName` may include the source version number (e.g. `pipe-spec:1.3.2`). If no version is supplied the highest version is used.\r\n\r\nThe `--versionType` option determines how the current version number is incremented (default is \"patch\").\r\n\r\nFor example, suppose the latest version is `pipe-spec:1.3.2`:\r\n\r\n```sh\r\n\r\n> WorkspaceEditor versionDb pipe-spec --versionType=major\r\ncreated new version: [pipe-spec:2.0.0] from [pipe-spec:1.3.2] in container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n\r\n - or -\r\n\r\n> WorkspaceEditor versionDb pipe-spec:1.3.2 --versionType=minor\r\ncreated new version: [pipe-spec:1.4.0] from [pipe-spec:1.3.2] in container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n\r\n - or -\r\n\r\n> WorkspaceEditor versionDb pipe-spec --versionType=patch\r\ncreated new version: [pipe-spec:1.3.3] from [pipe-spec:1.3.2] in container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n\r\n - or -\r\n\r\n> WorkspaceEditor versionDb pipe-spec\r\ncreated new version: [pipe-spec:1.3.3] from [pipe-spec:1.3.2] in container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n\r\n```\r\n\r\n> The examples above are not intended to illustrate sequential commands. Once you make a new version of a WorkspaceDb, you may begin editing it. But you cannot make another version until you release the write lock.\r\n\r\n### queryDbs [glob]\r\n\r\nShow a list of all `WorkspaceDb` in a cloud `WorkspaceContainer`.\r\n\r\nThe optional `glob` argument can be used to filter the results using the SQLite [GLOB](https://www.sqlite.org/lang_expr.html#glob) operator.\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor queryDbs\r\nWorkspaceDbs in container [5d385232-a2ec-4f31-b74b-8201c027848d], writeLocked, has local changes\r\n \"ame-ria:1.0.0\", size=24M, 0M downloaded (0%)\r\n \"base-data:1.0.0\", size=144M, 0M downloaded (0%)\r\n \"base-data:1.0.1\", size=144M, 12M downloaded (9%)\r\n \"proj:1.0.0\", size=4M, 4M downloaded (100%)\r\n \"proj:1.0.1\", size=4M, 4M downloaded (100%)\r\n \"proj:1.1.0\", size=4M, 4M downloaded (100%), editable\r\n\r\n> WorkspaceEditor queryDbs b*\r\nWorkspaceDbs in container [5d385232-a2ec-4f31-b74b-8201c027848d], writeLocked, has local changes\r\n \"base-data:1.0.0\", size=144M, 0M downloaded (0%)\r\n \"base-data:1.0.1\", size=144M, 12M downloaded (9%)\r\n```\r\n\r\nThe output also shows:\r\n\r\n- whether the write lock is held\r\n- whether there are local changes to be uploaded\r\n- whether there are garbage blocks that can be purged\r\n- for each `WorkspaceDb`:\r\n  - its full name with version\r\n  - its total size\r\n  - number of bytes downloaded and percentage\r\n  - whether the database is editable\r\n\r\n### exportDb \\<dbName> \\<localFileName>\r\n\r\nExport a `WorkspaceDb` from a cloud `WorkspaceContainer` into a local file.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor exportDb proj:1.0.1 d:\\temp\\proj\r\nexport d:\\temp\\proj.itwin-workspace, container=5d385232-a2ec-4f31-b74b-8201c027848d, dbName=proj:1.0.1 : complete, 0.013 seconds\r\n```\r\n\r\n> `dbName` must include a version number.\r\n\r\n### deleteDb \\<dbName>\r\n\r\nDelete a `WorkspaceDb` from a cloud `WorkspaceContainer`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEditor deleteDb proj3dt:2.0.0\r\ndeleted WorkspaceDb [proj3dt:2.0.0] from container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n```\r\n\r\nThis command is not normally used, since older versions of `WorkspaceDb`s may be used by existing or archived projects. It should *only* be used when it can be known that the `WorkspaceDb` is no longer needed for any purpose. Otherwise, leaving old versions in the cloud has very little downside.\r\n\r\n> `dbName` must include a version number.\r\n\r\n### purgeWorkspace\r\n\r\nDelete currently unused blocks from a cloud `WorkspaceContainer`. This is only necessary or useful after vacuuming databases.\r\n\r\n## @ scripts\r\n\r\nIt is sometimes necessary to run WorkspaceEditor in *batch mode*, for example during pipeline jobs. If the first argument to WorkspaceEditor begins with an \"@\", the rest of the argument is a file name from which WorkspaceEditor commands are executed in sequence.\r\n\r\nThe second argument can specify the config file for the script.\r\n\r\n> In @ scripts, anything after an **`#`** is treated as a comment and blank lines are ignored.\r\n\r\nFor example, to run the examples above:\r\n\r\nAssume a file called `importAll.txt` contains:\r\n\r\n```sh\r\n> cat importAll.txt\r\n\r\n# Create a new local WorkspaceDb file and import resources into it\r\n\r\ncreateDb proj # create a new blank WorkspaceDb\r\nadd proj --rscName=equipment-data --type=file r:\\data\\equip.dat # add file\r\nadd proj --type=string --root=r:\\json * # add strings\r\nadd proj --type=blob --root=r:\\dict **\\*.dict # add blob\r\nlistDb proj # so we can tell it worked\r\n```\r\n\r\nrun `importAll.txt` as an @ script using `local.json` as config:\r\n\r\n```sh\r\n> WorkspaceEditor @importAll.txt --config=r:\\local.json\r\ncreated WorkspaceDb r:\\workspaces\\proj112\\proj.itwin-workspace\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:/data/equip.dat\" as file resource [equipment-data]\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:\\json\\contracts.json\" as string resource [contracts.json]\r\n added \"r:\\json\\firecode.json\" as string resource [firecode.json]\r\n added \"r:\\json\\specs.json\" as string resource [specs.json]\r\n added \"r:\\json\\vendor.json\" as string resource [vendor.json]\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n added \"r:\\dict\\Sparks\\KDE05814.dict\" as blob resource [Sparks/KDE05814.dict]\r\n added \"r:\\dict\\Sparks\\KDE05815.dict\" as blob resource [Sparks/KDE05815.dict]\r\n added \"r:\\dict\\Sparks\\KDE05816.dict\" as blob resource [Sparks/KDE05816.dict]\r\n added \"r:\\dict\\Sparks\\KDE05922.dict\" as blob resource [Sparks/KDE05922.dict]\r\n added \"r:\\dict\\Sparks\\KDE05929.dict\" as blob resource [Sparks/KDE05929.dict]\r\n added \"r:\\dict\\TernKit\\TRN02324.dict\" as blob resource [TernKit/TRN02324.dict]\r\n added \"r:\\dict\\TernKit\\TRN05314.dict\" as blob resource [TernKit/TRN05314.dict]\r\n added \"r:\\dict\\TernKit\\TRN05814.dict\" as blob resource [TernKit/TRN05814.dict]\r\n added \"r:\\dict\\TernKit\\TRN09911.dict\" as blob resource [TernKit/TRN09911.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05554.dict\" as blob resource [UniSpace/KRT05554.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05800.dict\" as blob resource [UniSpace/KRT05800.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05814.dict\" as blob resource [UniSpace/KRT05814.dict]\r\n added \"r:\\dict\\UniSpace\\KRT05820.dict\" as blob resource [UniSpace/KRT05820.dict]\r\n added \"r:\\dict\\UniSpace\\KRT06519.dict\" as blob resource [UniSpace/KRT06519.dict]\r\nWorkspaceDb [r:\\workspaces\\proj112\\proj.itwin-workspace]\r\n strings:\r\n  name=contracts.json, size=17K\r\n  name=firecode.json, size=3K\r\n  name=specs.json, size=8K\r\n  name=vendor.json, size=46K\r\n blobs:\r\n  name=Sparks/KDE05814.dict, size=224K\r\n  name=Sparks/KDE05815.dict, size=307K\r\n  name=Sparks/KDE05816.dict, size=32K\r\n  name=Sparks/KDE05922.dict, size=56K\r\n  name=Sparks/KDE05929.dict, size=15K\r\n  name=TernKit/TRN02324.dict, size=405\r\n  name=TernKit/TRN05314.dict, size=67K\r\n  name=TernKit/TRN05814.dict, size=7K\r\n  name=TernKit/TRN09911.dict, size=3K\r\n  name=UniSpace/KRT05554.dict, size=2K\r\n  name=UniSpace/KRT05800.dict, size=5K\r\n  name=UniSpace/KRT05814.dict, size=13K\r\n  name=UniSpace/KRT05820.dict, size=7K\r\n  name=UniSpace/KRT06519.dict, size=687\r\n files:\r\n  name=equipment-data, size=134K, ext=\"dat\", date=Tue Jul 08 2014 13:55:19 GMT-0400 (Eastern Daylight Time)\r\n```\r\n\r\nThen, a separate file called `createCloud.txt` contains:\r\n\r\n```sh\r\n> cat createCloud.txt\r\n\r\n# initialize container and import WorkspaceDb from previous step\r\n\r\ninitializeWorkspace --noPrompt # don't prompt for yes/no\r\nimportDb project proj112\\proj # import WorkspaceDb from local directory into cloud container.\r\nqueryDbs # so we can tell it worked\r\n```\r\nrun `createCloud.txt` as an @ script using `cloud.json` for config:\r\n\r\n```sh\r\n> WorkspaceEditor @r:\\createCloud.txt --config=r:\\cloud.json\r\ncontainer \"5d385232-a2ec-4f31-b74b-8201c027848d initialized\r\nVacuuming r:\\workspaces\\proj112\\proj.itwin-workspace ... done\r\nimport r:\\workspaces\\proj112\\proj.itwin-workspace, container=5d385232-a2ec-4f31-b74b-8201c027848d, dbName=project:1.0.0 : complete, 0.047 seconds\r\nWorkspaceDbs in container [5d385232-a2ec-4f31-b74b-8201c027848d]\r\n \"project:1.0.0\", size=4M, 0M downloaded (0%)\r\n ```\r\n"
+  }
 }