Merge branch 'main' of https://github.com/iTwin/itwin-cli into wolfo951/context-implementation

Author: wolfo951

.github/workflows/ci.yaml

@@ -49,4 +49,5 @@ jobs:
           ITP_ISSUER_URL: ${{ vars.ITP_ISSUER_URL }}
           ITP_SERVICE_CLIENT_ID: ${{ vars.ITP_SERVICE_CLIENT_ID }}
           ITP_SERVICE_CLIENT_SECRET: ${{ secrets.ITP_SERVICE_CLIENT_SECRET }}
+          ITP_MAILINATOR_API_KEY: ${{ secrets.ITP_MAILINATOR_API_KEY }}
         run: npm run test

.vscode/launch.json

@@ -18,6 +18,18 @@
                 "<itwin-id>"
             ]
         },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch docs generator",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}\\bin\\run",
+            "args": [
+                "docs-generator"
+            ]
+        },
         {
             "name": "Debug All Tests",
             "skipFiles": [
@@ -30,7 +42,7 @@
                 "--forbid-only",
                 "--timeout",
                 "999999",
-                "integration-tests/**/api.test.ts"
+                "integration-tests/**/*.test.ts"
             ],
             "console": "integratedTerminal",
             "internalConsoleOptions": "neverOpen"

docs/_sidebar.md

@@ -1,4 +1,5 @@
 * [iTwin CLI Manual](/docs/)
+* [iTwin 101](/docs/itwin101.md)
 * [Quickstart](/docs/quickstart.md)
 * [Workflows](/docs/workflows/overview.md)
 

docs/imodel/view/cesium-sandcastle.md

@@ -7,8 +7,8 @@ Setup iModel and get URL to view it in Cesium Sandcastle.
 ## Options
 
 - **`--changeset-id`**  
-  Changeset id to be viewed in Cesium Sandcastle.  
-  **Type:** `string` **Required:** Yes
+  Changeset id to be viewed in Cesium Sandcastle. If not provided, the latest changeset will be used.
+  **Type:** `string` **Required:** No
 
 - **`-m, --imodel-id`**  
   iModel id to be viewed in Cesium Sandcastle.  

docs/itwin101.md

@@ -0,0 +1,134 @@
+# iTwin 101
+
+**A developer-friendly introduction to Bentley's iTwin Platform.**
+
+The infrastructure industry has undergone a major shift — from static design files to **cloud-connected systems** that reflect how assets behave in real time.
+
+This shift is driven by the rise of **digital twins**: living models that combine infrastructure design with data from numerous cloud sources for a complete view of the asset. For example, a dam reporting structural health and energy output, or a smart building tracking occupancy, lighting, and air quality. It’s no longer just about designing — it’s about how an asset lives and performs in the real world.
+
+**Bentley Systems**, a long-standing leader in infrastructure software, created the **iTwin Platform** to support this evolution. While desktop tools like **MicroStation** and **AutoCAD** have supported infrastructure design for decades, the iTwin Platform brings this data into the cloud — where teams can visualize entire assets, integrate live data, and build connected solutions across industries.
+
+Following Bentley’s acquisition of **Cesium**, high-performance 3D geospatial visualization is now a built-in part of the iTwin ecosystem. **Cesium** is an open platform for streaming large-scale 3D data, and its developer sandbox, **Sandcastle**, makes it easy to prototype and interact with infrastructure in a global context.
+
+The **iTwin CLI** ties it all together — letting you manage iTwins, bring design data into the cloud, and visualize your models in Cesium Sandcastle — all from the command line.
+
+---
+
+### 🎓 What Is a Digital Twin?
+
+A **digital twin** is more than a design model. It’s a cloud-based, real-time digital representation of a physical asset—like a building, bridge, highway, or dam. A digital twin integrates multiple data layers:
+
+- **👩‍🔧 Design Data**: CAD and BIM models created using tools like MicroStation, Revit, AutoCAD, etc.
+- **🌍 Reality Data**: Photogrammetry, point clouds, and 3D meshes captured by drones or scanners.
+- **📈 Sensor Data**: Live IoT data reflecting asset performance, environmental conditions, and more.
+- **📂 External Repositories**: Additional cloud data sources that enrich the digital twin's context.
+
+What makes a digital twin powerful is the way these sources come together in the cloud to form a "living" version of an asset—something that's not just visual, but interactive and analyzable.
+
+---
+
+### 🪧 Enter the iTwin
+
+The **iTwin** is Bentley’s implementation of a digital twin—a central hub that brings together all the data related to an infrastructure asset. It's built to be open, extensible, and deeply interoperable.
+
+At its core, an iTwin includes several key components:
+
+#### 🧱 iModel: Design Data, Standardized
+
+An **iModel** is a specialized cloud repository for 3D design data. It acts as a **common data environment** that unifies models from various design applications (MicroStation, Revit, Civil3D, etc.) into a single, coherent format.
+
+> Have a Revit file for a building? Add it to the iModel.  
+> Got utility designs from MicroStation? Add them too.
+
+The iModel isn’t just a storage format—it acts like **Git for infrastructure**. Designers "synchronize" their changes, which are stored as **changesets**. This allows for collaborative workflows, version tracking, and comparison of changes between versions.
+
+#### 🌎 Reality Data: Contextual Visualization
+
+Drones, scanners, and photogrammetry can capture detailed environmental data around your asset. This is imported into the iTwin to create photorealistic context and increase the accuracy of both design and decision-making.
+
+#### 📊 Sensor Data: Real-Time Awareness
+
+Digital twins aren’t just static snapshots. By integrating sensor or IoT data, iTwins reflect real-world conditions in real time. Think:
+
+- Energy usage
+- Equipment performance
+- Occupancy levels
+- Fault detection
+
+This makes the iTwin a true operational tool, not just a design archive.
+
+#### 📚 External Data: Extendable by Nature
+
+Need to connect to a custom database, web API, or document store? The iTwin is designed to consume and present external data as part of its interface. Through widgets, charts, or overlays, the twin can be tailored to meet specific business or project needs.
+
+---
+
+### ⚙️ The Role of the iTwin CLI
+
+The **iTwin CLI** is a command-line tool that lets developers and technical users interact with the iTwin Platform through simple text commands. It simplifies many common tasks:
+
+- ✍️ **Create and manage iTwins**
+- 🛡️ **Set up access control and user roles**
+- 🔍 **Query or inspect metadata**
+- 📂 **Create iModels and populate them with design files**
+- 📰 **Track and compare changes with changesets**
+- 🔢 **Create named versions to mark project milestones**
+- ⇄ **Synchronize design data into the iModel**
+- 🌍 **Visualize the iTwin in Cesium Sandcastle**
+
+It serves as a lightweight, scriptable gateway into a powerful ecosystem.
+
+---
+
+### 🗂️ iModels and Version Control
+
+Think of the iModel like Git. Multiple designers can work in parallel and synchronize changes when ready. Each sync produces a set of **changesets** that are stored with full history. This allows you to:
+
+- 📋 See who made which change
+- 🕓 Inspect previous states
+- ⚖️ Compare two versions to highlight changed elements
+
+You can also create **named versions** at key milestones: design freezes, review submissions, final approvals, etc.
+
+This not only supports tracking and review, but also enables advanced visualization and automation possibilities.
+
+---
+
+### 🗃️ Storage and Synchronization
+
+iTwins contain a dedicated storage repository where design files and project documents can be centrally managed. This storage acts as a staging area for incoming files before they're synchronized into an iModel.
+
+The iTwin CLI supports using this shared storage to:
+
+- 📤 Upload and organize design files
+- 🔄 Sync them into the iModel
+- 📎 Add documents and media (PDFs, photos, drawings)
+
+Files uploaded into iTwin storage can be selectively synchronized using **connections** to control what gets added to the iModel and when.
+
+---
+
+### 🌐 Geospatial Visualization with Cesium
+
+One of the most exciting features of the iTwin CLI is integration with **Cesium Sandcastle**, CesiumJS's interactive 3D globe environment.
+
+> Push your iTwin to Sandcastle and instantly visualize infrastructure assets in a real-world geospatial context.
+
+Design data becomes globally interactive. Combined with reality meshes and IoT data, it opens up new opportunities for:
+
+- High-performance 3D visualization
+- Infrastructure analytics
+- Immersive design review
+- Public or stakeholder presentations
+
+---
+
+### ✨ Wrapping Up
+
+The iTwin CLI makes it easy to build, manage, and explore digital twins using the iTwin Platform. For anyone interested in geospatial technology and digital twin workflows, it opens a new path to work with infrastructure data at scale, integrate diverse data sources, and publish them to a geospatially rich, interactive viewer.
+
+Whether you’re just exploring or already building, the iTwin CLI is your entry point into a next-generation platform for digital infrastructure.
+
+---
+
+**Next up:** [Quickstart Guide →](/docs/quickstart.md)

integration-tests/access-control/member/owner.ts

@@ -10,12 +10,13 @@ import { expect } from "chai";
 import { groupMember } from "../../../src/services/access-control-client/models/group-members";
 import { ownerResponse } from "../../../src/services/access-control-client/models/owner";
 import { User } from "../../../src/services/user-client/models/user";
+import { fetchEmailsAndGetInvitationLink } from "../../utils/helpers";
 
 const tests = () => {
     let iTwinId: string;
+    const iTwinName: string = `cli-itwin-integration-test-${new Date().toISOString()}`;
 
     before(async () => {
-        const iTwinName = `cli-itwin-integration-test-${new Date().toISOString()}`;
         const iTwin = await runCommand<ITwin>(`itwin create --class Thing --sub-class Asset --name ${iTwinName}`);
         expect(iTwin.result?.id).is.not.undefined;
         iTwinId = iTwin.result!.id!;
@@ -26,13 +27,27 @@ const tests = () => {
         expect(result.stdout).to.contain('deleted');
     });
 
-    it('Should add new owner to an iTwin', async () => {
-        const emailToAdd = 'itwin.cli.qa-testaccount@be-mailinator.eastus.cloudapp.azure.com';
-        const owner = await runCommand<ownerResponse>(`access-control member owner add -i ${iTwinId} --email ${emailToAdd}`);
-        expect(owner.result).is.not.undefined;
-        expect(owner.result!.member).is.null;
-        expect(owner.result!.invitation).is.not.undefined;
-        expect(owner.result!.invitation.email).to.equal(emailToAdd);
+    it('Should invite an external member to an iTwin, accept invitation and remove owner member', async () => {
+        const emailToAdd = 'iTwin.CLI.QA.IntegrationTest@bentley.m8r.co';
+        const invitedOwner = await runCommand<ownerResponse>(`access-control member owner add -i ${iTwinId} --email ${emailToAdd}`);
+        expect(invitedOwner.result).is.not.undefined;
+        expect(invitedOwner.result!.member).is.null;
+        expect(invitedOwner.result!.invitation).is.not.undefined;
+        expect(invitedOwner.result!.invitation.email.toLowerCase()).to.equal(emailToAdd.toLowerCase());
+
+        const invitationLink = await fetchEmailsAndGetInvitationLink(emailToAdd.split('@')[0], iTwinName);
+
+        await fetch(invitationLink);
+
+        const usersInfo = await runCommand<groupMember[]>(`access-control member owner list --itwin-id ${iTwinId}`);
+        expect(usersInfo.result).is.not.undefined;
+        expect(usersInfo.result!.length).to.be.equal(2);
+        const joinedUser = usersInfo.result?.filter(user => user.email.toLowerCase() === emailToAdd.toLowerCase())[0];
+        expect(joinedUser).to.not.be.undefined;
+
+        const deletionResult = await runCommand<{result: string}>(`access-control member owner delete --itwin-id ${iTwinId} --member-id ${joinedUser?.id}`);
+        expect(deletionResult.result).to.not.be.undefined;
+        expect(deletionResult.result!.result).to.be.equal("deleted");
     });
 
     it('Should list owners of an iTwin', async () => {

integration-tests/access-control/member/user.ts

@@ -7,15 +7,16 @@ import { ITwin } from "@itwin/itwins-client";
 import { runCommand } from "@oclif/test";
 import { expect } from "chai";
 
-import { member } from "../../../src/services/access-control-client/models/members";
+import { member, membersResponse } from "../../../src/services/access-control-client/models/members";
 import { Role } from "../../../src/services/access-control-client/models/role";
 import { User } from "../../../src/services/user-client/models/user";
+import { fetchEmailsAndGetInvitationLink } from "../../utils/helpers";
 
 const tests = () => {
     let iTwinId: string;
+    const iTwinName: string = `cli-itwin-integration-test-${new Date().toISOString()}`;
 
     before(async () => {
-        const iTwinName = `cli-itwin-integration-test-${new Date().toISOString()}`;
         const iTwin = await runCommand<ITwin>(`itwin create --class Thing --sub-class Asset --name ${iTwinName}`);
         expect(iTwin.result?.id).is.not.undefined;
         iTwinId = iTwin.result!.id!;
@@ -26,7 +27,39 @@ const tests = () => {
         expect(result.stdout).to.contain('deleted');
     });
 
-    it('Should dispaly owner info of an iTwin in member info', async () => {
+    it('Should invite an external member to an iTwin, accept sent invitation and remove user member', async () => {
+        const newRole = await runCommand<Role>(`access-control role create -i ${iTwinId} -n "Test Role 1" -d "Test Role Description"`);
+        expect(newRole.result).is.not.undefined;
+        expect(newRole.result!.id).is.not.undefined;
+        
+        const emailToAdd = 'iTwin.CLI.QA.IntegrationTest@bentley.m8r.co';
+
+        const invitedUser = await runCommand<membersResponse>(`access-control member user add --itwin-id ${iTwinId} --members "[{"email": "${emailToAdd}", "roleIds": ["${newRole.result!.id}"]}]"`);
+
+        expect(invitedUser.result).to.not.be.undefined;
+        expect(invitedUser.result!.invitations.length).to.be.equal(1);
+        expect(invitedUser.result!.invitations[0].email.toLowerCase()).to.be.equal(emailToAdd.toLowerCase());
+        expect(invitedUser.result!.invitations[0].roles.length).to.be.equal(1);
+        expect(invitedUser.result!.invitations[0].roles[0].id).to.be.equal(newRole.result!.id);
+
+        const invitationLink = await fetchEmailsAndGetInvitationLink(emailToAdd.split('@')[0], iTwinName);
+
+        await fetch(invitationLink);
+
+        const usersInfo = await runCommand<member[]>(`access-control member user list --itwin-id ${iTwinId}`);
+        expect(usersInfo.result).is.not.undefined;
+        expect(usersInfo.result!.length).to.be.equal(2);
+        const joinedUser = usersInfo.result?.filter(user => user.email.toLowerCase() === emailToAdd.toLowerCase())[0];
+        expect(joinedUser).to.not.be.undefined;
+        expect(joinedUser?.roles.length).to.be.equal(1);
+        expect(joinedUser?.roles[0].id).to.be.equal(newRole.result!.id);
+
+        const deletionResult = await runCommand<{result: string}>(`access-control member user delete --itwin-id ${iTwinId} --member-id ${joinedUser?.id}`);
+        expect(deletionResult.result).to.not.be.undefined;
+        expect(deletionResult.result!.result).to.be.equal("deleted");
+    });
+
+    it('Should display owner info of an iTwin in member info', async () => {
         const userInfo = await runCommand<User>(`user me`);
         expect(userInfo.result).is.not.undefined;
 
@@ -37,7 +70,7 @@ const tests = () => {
     });
 
     it('Should add new member to an iTwin and update the role', async () => {
-        const newRole = await runCommand<Role>(`access-control role create -i ${iTwinId} -n "Test Role" -d "Test Role Description"`);
+        const newRole = await runCommand<Role>(`access-control role create -i ${iTwinId} -n "Test Role 2" -d "Test Role Description"`);
         expect(newRole.result).is.not.undefined;
         expect(newRole.result!.id).is.not.undefined;
 

integration-tests/formating/formatting.test.ts

@@ -11,7 +11,7 @@ describe('Command formatting tests', async () => {
             userPlugins: false,
         });
 
-        allCommands = config.commands.filter(command => !command.id.startsWith("plugins") && !command.id.startsWith("help"))
+        allCommands = config.commands.filter(command => !command.id.startsWith("plugins") && !command.id.startsWith("help") && !command.hidden)
                                      .map((command) => 
                                      ({
                                          cmd: command,
@@ -32,12 +32,29 @@ describe('Command formatting tests', async () => {
                 expect(flag, `Flag '${flagName}' in command '${command.cmd.id}' is missing the 'required' property`).to.have.property('required');
 
                 if(flag.type === 'option') {
-                    console.log(flag);
                     expect(flag, `Flag '${flagName}' in command '${command.cmd.id}' is missing a valid 'helpValue'`).to.have.property('helpValue').to.be.a('string').and.not.be.empty;
                 }
             }
         }
     });
+
+    it('Should ensure all itwin-id flags have env properties', async () => {
+        for (const command of allCommands) {
+            const iTwinIdFlag = command.flags.find(([name, _]) => name === "itwin-id");
+            if (iTwinIdFlag) {
+                expect(iTwinIdFlag[1].env, `Flag 'itwin-id' in command '${command.cmd.id}' is missing the 'env' property`).to.be.a('string').and.be.equals("ITP_ITWIN_ID");
+            }
+        }
+    });
+
+    it('Should ensure all imodel-id flags have env properties', async () => {
+        for (const command of allCommands) {
+            const iTwinIdFlag = command.flags.find(([name, _]) => name === "imodel-id");
+            if (iTwinIdFlag) {
+                expect(iTwinIdFlag[1].env, `Flag 'imodel-id' in command '${command.cmd.id}' is missing the 'env' property`).to.be.a('string').and.be.equals("ITP_IMODEL_ID");
+            }
+        }
+    });
 });
 
 type CommandWithFlags = {