cu-cli 0.1.0b1__tar.gz

cu_cli-0.1.0b1/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: cu-cli
+Version: 0.1.0b1
+Summary: Author, validate, and run Azure Content Understanding custom analyzers from the terminal — advanced document layout, industry-leading OCR, and grounded field extraction with confidence, all backed by Azure Content Understanding.
+Author: Microsoft Corporation
+License: MIT
+Project-URL: Homepage, https://github.com/Azure/content-understanding-toolkit/tree/main/cu-cli
+Project-URL: Repository, https://github.com/Azure/content-understanding-toolkit
+Project-URL: Issues, https://github.com/Azure/content-understanding-toolkit/issues
+Project-URL: Documentation, https://aka.ms/cu-doc
+Keywords: azure,content-understanding,document-intelligence,ocr,pdf,extract,field-extraction,analyzer,cli,markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cu-cli-core<0.2.0,>=0.1.0b1
+Requires-Dist: azure-ai-contentunderstanding>=1.2.0b3
+Requires-Dist: azure-identity>=1.19
+Requires-Dist: azure-mgmt-cognitiveservices>=13.5
+Requires-Dist: click>=8.1
+Requires-Dist: packaging>=23.2
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Requires-Dist: rich-click>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: mypy<2,>=1.8; extra == "dev"
+Requires-Dist: ruff<0.16,>=0.5; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Requires-Dist: vcrpy>=6.0; extra == "dev"
+
+# CU CLI
+
+`cu` is the preview command-line interface for Azure Content Understanding in
+Foundry Tools. Use it to provision the required Microsoft Foundry resource,
+optionally deploy selected supported large language models (LLMs) and embeddings
+models, configure Content Understanding defaults, analyze local files, manage
+analyzers, and manage local configuration.
+
+> [!IMPORTANT]
+> CU CLI is in preview. Commands and package contracts may change before general
+> availability.
+
+## Content Understanding concepts
+
+Content Understanding processes unstructured content, including documents,
+images, audio, and video, into structured output for automation, analytics, and
+search workflows. It is a Foundry Tool that you access through a Microsoft
+Foundry resource in Azure.
+
+The Content Understanding documentation uses these terms:
+
+- A **file** is the input. It can be a document, image, audio file, video, or
+  other [supported file type](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits).
+- An **analyzer** defines how Content Understanding processes a file and
+  extracts content and structured fields.
+- An **analyzer result** is the output from processing a file. It can include
+  extracted Markdown content, structured fields, and modality-specific details.
+- A **prebuilt analyzer** is a ready-to-use analyzer supplied by Content
+  Understanding for common content extraction, search, and domain scenarios.
+- A **custom analyzer** is an analyzer you define for your scenario. It uses a
+  base analyzer for a content type and a field schema that describes the
+  structured fields to extract.
+
+CU CLI lets you configure a Microsoft Foundry resource, select an analyzer,
+submit local files, and save analyzer results without calling the REST API
+directly.
+
+Further reading:
+
+- [What is Content Understanding?](https://learn.microsoft.com/azure/ai-services/content-understanding/overview)
+- [Content Understanding terminology](https://learn.microsoft.com/azure/ai-services/content-understanding/glossary)
+
+## Install
+
+Requirements:
+
+- Python 3.10 or later
+- [Azure CLI](https://aka.ms/azcli) for login and resource discovery
+- [Azure Developer CLI](https://aka.ms/azd) only when using `cu infra generate`
+
+```bash
+python -m pip install cu-cli
+cu --version
+cu --help
+```
+
+macOS includes an unrelated system command named `cu`. Use the equivalent
+`cu-cli` executable on macOS:
+
+```bash
+cu-cli --help
+```
+
+## Connect to Microsoft Foundry and check setup
+
+You need a Microsoft Foundry resource endpoint. LLM-based prebuilt analyzers and
+custom analyzers also need supported LLM and embeddings deployments plus Content
+Understanding defaults. If any of these are missing, follow the complete
+[Microsoft Foundry provisioning guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md).
+
+A CU CLI profile is local configuration for one Microsoft Foundry resource. It
+stores the endpoint, authentication method, API version, and optional model
+deployment mappings; it is not an Azure resource. For a ready resource,
+configure the automatically available `default` profile. With Microsoft Entra
+ID authentication:
+
+```bash
+cu profile set endpoint https://<resource-name>.services.ai.azure.com/
+cu profile set auth_mode login
+az login
+cu doctor
+```
+
+Alternatively, use a resource key:
+
+```bash
+cu profile set endpoint https://<resource-name>.services.ai.azure.com/
+cu profile set api_key <key>
+cu doctor
+```
+
+The API key is redacted by `cu profile get` and `cu profile show`. `cu doctor`
+checks the API version, endpoint, authentication, service connectivity, and
+Content Understanding defaults. It exits nonzero when a required check fails,
+so it can serve as a readiness gate.
+
+## Supported Content Understanding API versions
+
+Content Understanding API version. Known versions: 2025-11-01 (GA) and
+2026-06-01-preview (preview); any YYYY-MM-DD-preview version is also accepted.
+
+CU CLI defaults to `2025-11-01`. Override the version with `cu profile set
+api_version <version>`, the `--api-version` flag, or the `CU_API_VERSION`
+environment variable; run `cu profile show` to see the active profile's
+configured version.
+
+The preview API adds capabilities beyond the GA version. CU CLI returns
+result-based capabilities, such as document metadata and signatures, through
+the normal analysis result without dedicated CLI options. Inline analysis is
+the only preview capability that requires a new CU CLI option:
+`cu analyze --inline` runs supported analysis synchronously and returns the
+result directly instead of using the default long-running-operation (LRO)
+polling flow.
+
+```bash
+cu analyze --inline --api-version 2026-06-01-preview document.pdf --analyzer prebuilt-layout
+```
+
+Save the preview version to a profile to avoid passing `--api-version` on every
+call: `cu profile set api_version 2026-06-01-preview`. Pin to `2025-11-01` for
+production workloads that don't need preview capabilities.
+
+Further reading:
+
+- [What's new in the `2026-06-01-preview` API](https://learn.microsoft.com/azure/ai-services/content-understanding/whats-new#july-2026)
+- Run `cu analyze --help` for all analyze options.
+
+## Use prebuilt analyzers
+
+List the prebuilt analyzers available to the configured resource:
+
+```bash
+cu analyzer list
+```
+
+Start with the `prebuilt-layout` content extraction analyzer. It extracts text,
+paragraphs, tables, figures, and document structure without requiring a language
+model or embeddings model. `-a` is the short form of `--analyzer`:
+
+```bash
+# Generate Markdown from the analyzer result with the CU SDK's to_llm_input().
+cu analyze ./document.pdf -a prebuilt-layout
+```
+
+Markdown generated by the Content Understanding SDK's `to_llm_input()` helper is
+the default output format. The helper formats field extraction results as
+Markdown with YAML frontmatter so they can be used as generative AI model input.
+Use `--llm-input` to select this default view explicitly, or use `--json` to
+return the complete analyzer result as JSON. See the
+[Content Understanding SDK `to_llm_input()` helper](https://learn.microsoft.com/azure/ai-services/content-understanding/whats-new#april-2026).
+
+Domain-specific prebuilt analyzers, such as `prebuilt-invoice`, extract a
+defined set of structured fields. They require the model setup described in
+[Deploy models and configure defaults](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md#deploy-models-and-configure-defaults):
+
+```bash
+cu analyze ./invoice.pdf --analyzer prebuilt-invoice --json
+```
+
+The command returns an analyzer result. Use `--json` when you want the
+structured result as JSON.
+
+Analyze several files into one output directory. `--pattern` requires
+`--source`, because a positional path can be either a file or a directory and
+`--pattern` only makes sense once a directory is named explicitly:
+
+```bash
+cu analyze --source ./documents --pattern "*.pdf" --output-dir ./results
+```
+
+Each result is written under `./results` and keeps the input path relative to
+`./documents`. For example, `./documents/invoice-01.pdf` produces
+`./results/invoice-01.pdf.result.md`. Markdown results use the
+`.result.md` suffix; adding `--json` produces `.result.json` files instead.
+
+Further reading:
+
+- [Prebuilt analyzers](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers)
+- [Supported input files and service limits](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits)
+- Run `cu analyze --help` for input, output, overwrite, concurrency, and reporting options.
+
+## Create a custom analyzer
+
+A custom analyzer lets you define the structured fields needed by your
+application. Its analyzer schema identifies a base analyzer for the content type
+and includes a field schema that describes the field names, value types, and
+generation methods.
+
+Custom analyzers require supported model deployments and configured Content
+Understanding defaults. Confirm the model-to-deployment mappings before creating
+the analyzer:
+
+```bash
+# Show the Content Understanding defaults configured on the resource.
+cu defaults show
+```
+
+If the required mappings are missing, follow
+[Configure defaults manually](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md#configure-defaults-manually)
+to configure them. Then generate a starter analyzer schema from a representative
+file:
+
+```bash
+# Generate a schema from a representative document.
+cu analyzer schema create \
+  --from-sample ./invoice.pdf \
+  --output-file ./invoice-schema.json
+
+# Review and update the generated schema for your extraction requirements,
+# then create the analyzer.
+cu analyzer create --name invoice_v1 --schema ./invoice-schema.json
+
+# Run the analyzer against the sample and summarize whether fields were returned
+# and any confidence values supplied by the service. This is not an accuracy
+# benchmark and does not compare the result with labeled ground truth.
+cu analyzer test invoice_v1 ./invoice.pdf
+
+cu analyze ./invoice.pdf --analyzer invoice_v1 --json
+```
+
+Schema generation preserves existing files by default. Pass `--force` only when
+you intentionally want to replace the selected `--output-file`.
+
+Further reading:
+
+- [Create a custom analyzer](https://learn.microsoft.com/azure/ai-services/content-understanding/tutorial/create-custom-analyzer)
+- [Supported generative models](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#supported-generative-models)
+- Run `cu analyzer --help` for analyzer management and testing commands.
+
+## Command overview
+
+| Command | Purpose |
+| --- | --- |
+| `cu analyze` | Analyze local files and return analyzer results. |
+| `cu analyzer` | List, show, create, copy, delete, and test analyzers; create and validate local analyzer schemas. |
+| `cu defaults` | Read or configure Content Understanding defaults that map models to deployments. |
+| `cu profile` | Manage local CU CLI endpoint, authentication, API, and model settings. |
+| `cu infra generate` | Generate an azd/Bicep project used to provision a Microsoft Foundry resource and configure Content Understanding. Run `azd up` to provision it. |
+| `cu doctor` | Verify the active CU CLI profile, authentication, and model readiness. |
+| `cu env-var` | Inspect supported environment-variable overrides. |
+
+Every command provides examples:
+
+```bash
+cu profile --help
+cu analyzer copy --help
+cu infra generate --help
+```
+
+## CU CLI usage guide
+
+Use this README for installation, resource connection, and the first successful
+analysis. For Azure provisioning, see the
+[Microsoft Foundry provisioning guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md). For detailed
+operational guidance, see the
+[CU CLI usage guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/usage-guide.md). It explains:
+
+- CU CLI profile resolution and environment-variable overrides
+- safe batch previews, output handling, and machine-readable reports
+- analyzer schema, lifecycle, testing, and cross-resource copy workflows
+- Content Understanding defaults and troubleshooting
+
+## More information
+
+- [Azure Content Understanding documentation](https://aka.ms/cu-doc)
+- [Support](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/SUPPORT.md)
+- [Contributing](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/CONTRIBUTING.md)
+
+The standalone distribution is `cu-cli`. It depends on the separately built
+`cu-cli-core` implementation package in this same product tree. `cu-cli-core`
+is an internal implementation boundary for official CU command-line frontends;
+install and use `cu-cli` rather than importing the core package directly.
+
+## Telemetry
+
+CU CLI adds `cu-cli/<version>` to the standard Azure SDK `User-Agent` header on
+requests to the Azure Content Understanding service. Microsoft uses this
+identifier to understand CU CLI adoption. CU CLI does not add customer content
+or separate usage and analytics events to this telemetry.
+
+To remove the `cu-cli/<version>` identifier, set `CU_TELEMETRY=off` (also
+accepts `0`, `false`, or `no`) before running CU CLI. The Azure SDK continues to
+send its standard `User-Agent` as part of service requests. See the repository
+[data collection notice](https://github.com/Azure/content-understanding-toolkit#data-collection)
+for more information.
+
+## Use multiple profiles
+
+If you work with multiple resources, create named profiles and either activate
+one or select it per command:
+
+```bash
+cu profile create dev
+cu profile set endpoint https://<dev-resource>.services.ai.azure.com/ --name dev
+cu profile create prod
+cu profile set endpoint https://<prod-resource>.services.ai.azure.com/ --name prod
+
+cu profile set-active dev
+cu analyzer list
+cu analyzer list --profile prod
+cu doctor --profile prod
+```
+
+See the [CU CLI profile usage guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/usage-guide.md#cu-cli-profiles) for
+profile resolution and environment-variable overrides.

cu_cli-0.1.0b1/README.md

@@ -0,0 +1,305 @@
+# CU CLI
+
+`cu` is the preview command-line interface for Azure Content Understanding in
+Foundry Tools. Use it to provision the required Microsoft Foundry resource,
+optionally deploy selected supported large language models (LLMs) and embeddings
+models, configure Content Understanding defaults, analyze local files, manage
+analyzers, and manage local configuration.
+
+> [!IMPORTANT]
+> CU CLI is in preview. Commands and package contracts may change before general
+> availability.
+
+## Content Understanding concepts
+
+Content Understanding processes unstructured content, including documents,
+images, audio, and video, into structured output for automation, analytics, and
+search workflows. It is a Foundry Tool that you access through a Microsoft
+Foundry resource in Azure.
+
+The Content Understanding documentation uses these terms:
+
+- A **file** is the input. It can be a document, image, audio file, video, or
+  other [supported file type](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits).
+- An **analyzer** defines how Content Understanding processes a file and
+  extracts content and structured fields.
+- An **analyzer result** is the output from processing a file. It can include
+  extracted Markdown content, structured fields, and modality-specific details.
+- A **prebuilt analyzer** is a ready-to-use analyzer supplied by Content
+  Understanding for common content extraction, search, and domain scenarios.
+- A **custom analyzer** is an analyzer you define for your scenario. It uses a
+  base analyzer for a content type and a field schema that describes the
+  structured fields to extract.
+
+CU CLI lets you configure a Microsoft Foundry resource, select an analyzer,
+submit local files, and save analyzer results without calling the REST API
+directly.
+
+Further reading:
+
+- [What is Content Understanding?](https://learn.microsoft.com/azure/ai-services/content-understanding/overview)
+- [Content Understanding terminology](https://learn.microsoft.com/azure/ai-services/content-understanding/glossary)
+
+## Install
+
+Requirements:
+
+- Python 3.10 or later
+- [Azure CLI](https://aka.ms/azcli) for login and resource discovery
+- [Azure Developer CLI](https://aka.ms/azd) only when using `cu infra generate`
+
+```bash
+python -m pip install cu-cli
+cu --version
+cu --help
+```
+
+macOS includes an unrelated system command named `cu`. Use the equivalent
+`cu-cli` executable on macOS:
+
+```bash
+cu-cli --help
+```
+
+## Connect to Microsoft Foundry and check setup
+
+You need a Microsoft Foundry resource endpoint. LLM-based prebuilt analyzers and
+custom analyzers also need supported LLM and embeddings deployments plus Content
+Understanding defaults. If any of these are missing, follow the complete
+[Microsoft Foundry provisioning guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md).
+
+A CU CLI profile is local configuration for one Microsoft Foundry resource. It
+stores the endpoint, authentication method, API version, and optional model
+deployment mappings; it is not an Azure resource. For a ready resource,
+configure the automatically available `default` profile. With Microsoft Entra
+ID authentication:
+
+```bash
+cu profile set endpoint https://<resource-name>.services.ai.azure.com/
+cu profile set auth_mode login
+az login
+cu doctor
+```
+
+Alternatively, use a resource key:
+
+```bash
+cu profile set endpoint https://<resource-name>.services.ai.azure.com/
+cu profile set api_key <key>
+cu doctor
+```
+
+The API key is redacted by `cu profile get` and `cu profile show`. `cu doctor`
+checks the API version, endpoint, authentication, service connectivity, and
+Content Understanding defaults. It exits nonzero when a required check fails,
+so it can serve as a readiness gate.
+
+## Supported Content Understanding API versions
+
+Content Understanding API version. Known versions: 2025-11-01 (GA) and
+2026-06-01-preview (preview); any YYYY-MM-DD-preview version is also accepted.
+
+CU CLI defaults to `2025-11-01`. Override the version with `cu profile set
+api_version <version>`, the `--api-version` flag, or the `CU_API_VERSION`
+environment variable; run `cu profile show` to see the active profile's
+configured version.
+
+The preview API adds capabilities beyond the GA version. CU CLI returns
+result-based capabilities, such as document metadata and signatures, through
+the normal analysis result without dedicated CLI options. Inline analysis is
+the only preview capability that requires a new CU CLI option:
+`cu analyze --inline` runs supported analysis synchronously and returns the
+result directly instead of using the default long-running-operation (LRO)
+polling flow.
+
+```bash
+cu analyze --inline --api-version 2026-06-01-preview document.pdf --analyzer prebuilt-layout
+```
+
+Save the preview version to a profile to avoid passing `--api-version` on every
+call: `cu profile set api_version 2026-06-01-preview`. Pin to `2025-11-01` for
+production workloads that don't need preview capabilities.
+
+Further reading:
+
+- [What's new in the `2026-06-01-preview` API](https://learn.microsoft.com/azure/ai-services/content-understanding/whats-new#july-2026)
+- Run `cu analyze --help` for all analyze options.
+
+## Use prebuilt analyzers
+
+List the prebuilt analyzers available to the configured resource:
+
+```bash
+cu analyzer list
+```
+
+Start with the `prebuilt-layout` content extraction analyzer. It extracts text,
+paragraphs, tables, figures, and document structure without requiring a language
+model or embeddings model. `-a` is the short form of `--analyzer`:
+
+```bash
+# Generate Markdown from the analyzer result with the CU SDK's to_llm_input().
+cu analyze ./document.pdf -a prebuilt-layout
+```
+
+Markdown generated by the Content Understanding SDK's `to_llm_input()` helper is
+the default output format. The helper formats field extraction results as
+Markdown with YAML frontmatter so they can be used as generative AI model input.
+Use `--llm-input` to select this default view explicitly, or use `--json` to
+return the complete analyzer result as JSON. See the
+[Content Understanding SDK `to_llm_input()` helper](https://learn.microsoft.com/azure/ai-services/content-understanding/whats-new#april-2026).
+
+Domain-specific prebuilt analyzers, such as `prebuilt-invoice`, extract a
+defined set of structured fields. They require the model setup described in
+[Deploy models and configure defaults](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md#deploy-models-and-configure-defaults):
+
+```bash
+cu analyze ./invoice.pdf --analyzer prebuilt-invoice --json
+```
+
+The command returns an analyzer result. Use `--json` when you want the
+structured result as JSON.
+
+Analyze several files into one output directory. `--pattern` requires
+`--source`, because a positional path can be either a file or a directory and
+`--pattern` only makes sense once a directory is named explicitly:
+
+```bash
+cu analyze --source ./documents --pattern "*.pdf" --output-dir ./results
+```
+
+Each result is written under `./results` and keeps the input path relative to
+`./documents`. For example, `./documents/invoice-01.pdf` produces
+`./results/invoice-01.pdf.result.md`. Markdown results use the
+`.result.md` suffix; adding `--json` produces `.result.json` files instead.
+
+Further reading:
+
+- [Prebuilt analyzers](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers)
+- [Supported input files and service limits](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits)
+- Run `cu analyze --help` for input, output, overwrite, concurrency, and reporting options.
+
+## Create a custom analyzer
+
+A custom analyzer lets you define the structured fields needed by your
+application. Its analyzer schema identifies a base analyzer for the content type
+and includes a field schema that describes the field names, value types, and
+generation methods.
+
+Custom analyzers require supported model deployments and configured Content
+Understanding defaults. Confirm the model-to-deployment mappings before creating
+the analyzer:
+
+```bash
+# Show the Content Understanding defaults configured on the resource.
+cu defaults show
+```
+
+If the required mappings are missing, follow
+[Configure defaults manually](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md#configure-defaults-manually)
+to configure them. Then generate a starter analyzer schema from a representative
+file:
+
+```bash
+# Generate a schema from a representative document.
+cu analyzer schema create \
+  --from-sample ./invoice.pdf \
+  --output-file ./invoice-schema.json
+
+# Review and update the generated schema for your extraction requirements,
+# then create the analyzer.
+cu analyzer create --name invoice_v1 --schema ./invoice-schema.json
+
+# Run the analyzer against the sample and summarize whether fields were returned
+# and any confidence values supplied by the service. This is not an accuracy
+# benchmark and does not compare the result with labeled ground truth.
+cu analyzer test invoice_v1 ./invoice.pdf
+
+cu analyze ./invoice.pdf --analyzer invoice_v1 --json
+```
+
+Schema generation preserves existing files by default. Pass `--force` only when
+you intentionally want to replace the selected `--output-file`.
+
+Further reading:
+
+- [Create a custom analyzer](https://learn.microsoft.com/azure/ai-services/content-understanding/tutorial/create-custom-analyzer)
+- [Supported generative models](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#supported-generative-models)
+- Run `cu analyzer --help` for analyzer management and testing commands.
+
+## Command overview
+
+| Command | Purpose |
+| --- | --- |
+| `cu analyze` | Analyze local files and return analyzer results. |
+| `cu analyzer` | List, show, create, copy, delete, and test analyzers; create and validate local analyzer schemas. |
+| `cu defaults` | Read or configure Content Understanding defaults that map models to deployments. |
+| `cu profile` | Manage local CU CLI endpoint, authentication, API, and model settings. |
+| `cu infra generate` | Generate an azd/Bicep project used to provision a Microsoft Foundry resource and configure Content Understanding. Run `azd up` to provision it. |
+| `cu doctor` | Verify the active CU CLI profile, authentication, and model readiness. |
+| `cu env-var` | Inspect supported environment-variable overrides. |
+
+Every command provides examples:
+
+```bash
+cu profile --help
+cu analyzer copy --help
+cu infra generate --help
+```
+
+## CU CLI usage guide
+
+Use this README for installation, resource connection, and the first successful
+analysis. For Azure provisioning, see the
+[Microsoft Foundry provisioning guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/provisioning.md). For detailed
+operational guidance, see the
+[CU CLI usage guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/usage-guide.md). It explains:
+
+- CU CLI profile resolution and environment-variable overrides
+- safe batch previews, output handling, and machine-readable reports
+- analyzer schema, lifecycle, testing, and cross-resource copy workflows
+- Content Understanding defaults and troubleshooting
+
+## More information
+
+- [Azure Content Understanding documentation](https://aka.ms/cu-doc)
+- [Support](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/SUPPORT.md)
+- [Contributing](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/CONTRIBUTING.md)
+
+The standalone distribution is `cu-cli`. It depends on the separately built
+`cu-cli-core` implementation package in this same product tree. `cu-cli-core`
+is an internal implementation boundary for official CU command-line frontends;
+install and use `cu-cli` rather than importing the core package directly.
+
+## Telemetry
+
+CU CLI adds `cu-cli/<version>` to the standard Azure SDK `User-Agent` header on
+requests to the Azure Content Understanding service. Microsoft uses this
+identifier to understand CU CLI adoption. CU CLI does not add customer content
+or separate usage and analytics events to this telemetry.
+
+To remove the `cu-cli/<version>` identifier, set `CU_TELEMETRY=off` (also
+accepts `0`, `false`, or `no`) before running CU CLI. The Azure SDK continues to
+send its standard `User-Agent` as part of service requests. See the repository
+[data collection notice](https://github.com/Azure/content-understanding-toolkit#data-collection)
+for more information.
+
+## Use multiple profiles
+
+If you work with multiple resources, create named profiles and either activate
+one or select it per command:
+
+```bash
+cu profile create dev
+cu profile set endpoint https://<dev-resource>.services.ai.azure.com/ --name dev
+cu profile create prod
+cu profile set endpoint https://<prod-resource>.services.ai.azure.com/ --name prod
+
+cu profile set-active dev
+cu analyzer list
+cu analyzer list --profile prod
+cu doctor --profile prod
+```
+
+See the [CU CLI profile usage guide](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/docs/usage-guide.md#cu-cli-profiles) for
+profile resolution and environment-variable overrides.