Metadata-Version: 2.4
Name: cu-cli
Version: 0.1.0b2
Summary: Run Azure Content Understanding prebuilt analyzers, and/or author, validate, and run 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.0b2
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. Analyze inputs can also be supplied
as HTTPS or Azure Blob SAS URLs.

> [!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 or HTTPS URLs, 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.

## Use `cu` and `az cu` interchangeably

The standalone CU CLI and the Azure CLI extension are two frontends over the
same `cu-cli-core` operations. Install either frontend, or install both and move
between them for the same analyzer, analysis, defaults, profile, diagnostics,
and infrastructure-generation workflows.

Both frontends read and write the same `[cu]` profile settings in the active
Azure CLI configuration file (`~/.azure/config` by default, or the file under
`AZURE_CONFIG_DIR`). An endpoint, API version, default analyzer, active profile,
or model-deployment mapping saved with one frontend is immediately available to
the other. For example:

```bash
# Save the endpoint with the standalone frontend.
cu profile set endpoint https://<resource-name>.services.ai.azure.com/

# Use the same default profile with the Azure CLI extension.
az cu analyzer list --output table

# Change the default analyzer with the Azure CLI extension.
az cu profile set --key default_analyzer --value prebuilt-layout

# Use that setting with the standalone frontend.
cu analyze ./document.pdf
```

The command names and capabilities overlap, but frontend conventions differ:

| Standalone CU CLI | Azure CLI extension |
| --- | --- |
| Starts commands with `cu` (`cu-cli` on macOS). | Starts commands with `az cu`. |
| Supports standalone positional shortcuts and Rich/JSON output options. | Uses explicit options plus global Azure CLI `--output`, `--query`, and `--subscription`. |
| Uses the profile's `auth_mode` and can use a saved API key. | Always uses the active `az login` identity; shared API keys and `auth_mode` do not override Azure CLI host authentication. |

Run `cu <command> --help` or `az cu <command> --help` when translating a command
between frontends. Profile values are shared; authentication sessions are not,
so sign in with `az login` before using `az cu`. For Azure CLI-specific
installation and command examples, see the
[Azure Content Understanding extension README](https://github.com/Azure/content-understanding-toolkit/blob/main/cu-cli/packages/azure-cli-extension/README.md).

## 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
```

Analyze a remote file with `--url` without downloading it through the CLI.
Quote URLs that contain SAS query parameters so the shell preserves `&` characters:

```bash
cu analyze --url "https://storage.example.net/container/video.mp4?sv=<version>&sp=r&sig=<signature>" \
  --analyzer prebuilt-videoSearch
```

Repeat `--url` for multiple URLs and specify `--output-dir` for their results.
`--url` cannot be combined with positional inputs, `--file`, or `--source`.
Positional URLs remain available as a standalone shortcut.

Remote inputs require HTTPS. Use a short-lived, read-only SAS and avoid placing
production SAS URLs in shared shell history. CU CLI removes URL query strings
from its status output and reports, while sending the original URL to Content
Understanding unchanged.

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 or HTTPS URLs 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.
