Environment variable guide (#100)

Author: roopksaini

docs/_sidebar.md

@@ -1,6 +1,7 @@
 * [iTwin CLI Manual](/docs/)
 * [iTwin 101](/docs/itwin101.md)
 * [Quickstart](/docs/quickstart.md)
+* [Environment](/docs/environment.md)
 * [Workflows](/docs/workflows/overview.md)
 
 <hr style="margin: 1em 5em 1em 1em; opacity: 0.1;">

docs/environment.md

@@ -0,0 +1,119 @@
+# Environment
+
+To reduce repetition and simplify usage, the CLI provides flexible ways to define your commonly used `iTwin` and `iModel` IDs. Once set, you can run commands without manually passing these IDs every time.
+
+The CLI supports two mechanisms for this:
+
+1. **Environment variables** — set manually in your terminal or CI environment
+2. **Local context** — managed via the `itp context` command
+
+Either approach can help streamline your workflow.
+
+---
+
+### Setting environment variables
+
+You can define your default IDs directly in the terminal environment:
+
+```bash
+// For macOS, Linux, WSL, Git Bash
+export ITP_ITWIN_ID=b1a2c3d4-5678-90ab-cdef-1234567890ab
+export ITP_IMODEL_ID=ad0ba809-9241-48ad-9eb0-c8038c1a1d51
+```
+
+```powershell
+// For PowerShell (Windows)
+$env:ITP_ITWIN_ID = "b1a2c3d4-5678-90ab-cdef-1234567890ab"
+$env:ITP_IMODEL_ID = "ad0ba809-9241-48ad-9eb0-c8038c1a1d51"
+```
+
+These values will be automatically picked up in commands unless overridden by context or flags.
+
+---
+
+### Using the `context` system
+
+The `itp context` command allows you to **save default iTwin and iModel IDs locally**. Once set, these values will persist across CLI sessions and be automatically used in commands.
+
+- Set context:
+
+  ```bash
+  itp context set --itwin-id <iTwinId> --imodel-id <iModelId>
+  ```
+
+- View current context:
+
+  ```bash
+  itp context info
+  ```
+
+- Clear context:
+
+  ```bash
+  itp context clear
+  ```
+
+> ℹ️ Context values take precedence over environment variables.
+
+---
+
+### Using the `--save` flag
+
+You can also update the context automatically during iTwin or iModel creation by using the `--save` flag. This stores the newly created ID into the local context, making it available for subsequent commands.
+
+- Save iTwin to context:
+
+  ```bash
+  itp itwin create --class Thing --sub-class Asset --name "Example iTwin" --save
+  ```
+
+- Save iModel to context:
+
+  ```bash
+  itp imodel create --name "Example iModel" --save
+  ```
+
+---
+
+### Resolution Order
+
+When determining which `iTwin ID` or `iModel ID` to use, the CLI resolves values in the following order:
+
+1. **Explicit flags passed in the command**
+2. **Values saved in `itp context`**
+3. **Environment variables (`ITP_ITWIN_ID`, `ITP_IMODEL_ID`)**
+4. **If none are provided → error**
+
+---
+
+### Examples
+
+**Without environment or context**
+
+```bash
+itp itwin info --itwin-id b1a2c3d4-5678-90ab-cdef-1234567890ab
+
+itp imodel populate   --imodel-id b1a2c3d4-5678-90ab-cdef-1234567890ab   --file file.dwg --connector-type DWG
+
+itp imodel named-version create   --imodel-id ad0ba809-9241-48ad-9eb0-c8038c1a1d51   --changeset-id 2f3b4a8c92d747d5c8a8b2f9cde6742e5d74b3b5   --name "Version 1.0" --description "Initial release"
+```
+
+**With environment variables or context**
+
+```bash
+# Assuming context or env variables are already set
+itp itwin info
+
+itp imodel populate --file file.dwg --connector-type DWG
+
+itp imodel named-version create   --changeset-id 2f3b4a8c92d747d5c8a8b2f9cde6742e5d74b3b5   --name "Version 1.0" --description "Initial design"
+```
+
+---
+
+### Summary
+
+- Passing `--itwin-id` or `--imodel-id` directly in a command will always override other sources.
+- Values set via `itp context` are stored locally and persist across sessions.
+- Environment variables (`ITP_ITWIN_ID`, `ITP_IMODEL_ID`) are ideal for scripting and temporary sessions.
+- If no IDs are received from any method, the CLI will return a **missing option** error.

docs/itwin101.md

@@ -1,14 +1,14 @@
 # iTwin 101
 
-**A developer-friendly introduction to Bentley's iTwin Platform.**
+**A 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.
+This shift is driven by the rise of **digital twins**: living models that combine infrastructure data to 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 infrastructure — 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.
+**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 infrastructure 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.
+Following Bentley’s acquisition of **Cesium**, high-performance 3D geo-spatial 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.
 
@@ -23,13 +23,13 @@ A **digital twin** is more than a design model. It’s a cloud-based, real-time
 - **📈 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.
+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.
+The **iTwin** is Bentley’s implementation of a digital twin — a central hub that brings together all the data related to an infrastructure asset into the cloud. It's built to be open, extensible, and deeply interoperable.
 
 At its core, an iTwin includes several key components:
 
@@ -40,11 +40,11 @@ An **iModel** is a specialized cloud repository for 3D design data. It acts as a
 > 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.
+The iModel isn’t just a storage format — it acts like **Git for infrastructure**. Designers commit  -  or in design words - **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.
+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 asset visualization and project decision-making.
 
 #### 📊 Sensor Data: Real-Time Awareness
 
@@ -127,7 +127,7 @@ Design data becomes globally interactive. Combined with reality meshes and IoT d
 
 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.
+Whether you’re just exploring or already building, the iTwin CLI is your entry point into the next-generation platform for the infrastructure digital twin.
 
 ---