Quickstart: Analyze a document with the Content Understanding CLI

In this quickstart, you use the CLI (azd ai cu) for Azure Content Understanding in Foundry Tools to extract document text and layout. You analyze a sample invoice with prebuilt-layout and save the result as Markdown or JSON.

Important

The CLI is in preview. Previews are provided without a service-level agreement and aren't recommended for production workloads. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

The CLI uses the 2025-11-01 GA service API by default. Its preview release status is separate from the service API version.

If you don't have an Azure subscription, create one for free.

Prerequisites

The commands in this quickstart work in Bash and PowerShell. You don't need Python, a language SDK, or an initialized azd project. The prebuilt-layout analyzer doesn't require language or embedding model deployments.

Install the Content Understanding extension

Confirm that azd is version 1.37.0 or later, then install the Content Understanding extension and check its version:

azd version
azd ext install azure.ai.content-understanding
azd ai cu version

Reference: azd version, extension commands.

The last command displays the extension ID and installed version, similar to this example. Your version might differ:

azure.ai.content-understanding 0.1.0-preview

Connect to your resource

Copy your resource endpoint from the Azure portal. Use the resource endpoint, such as https://<resource-name>.services.ai.azure.com/, not a Foundry project URL.

If you already have a saved endpoint, note its value with azd ai cu config get CU_ENDPOINT before replacing it.

Sign in, save the endpoint as a CLI user default, and check your connection. Replace <your-resource-endpoint> with your endpoint:

azd auth login
azd ai cu config set CU_ENDPOINT "<your-resource-endpoint>"
azd ai cu doctor

Reference: Connect to Microsoft Foundry and check setup.

The saved endpoint is available in future sessions without azd init. Shell variables and applicable azd environment settings take precedence over this saved default. The doctor report shows the effective settings and their sources.

Resolve any authentication or resource-access errors before continuing. A warning about missing generative model defaults doesn't prevent you from using prebuilt-layout.

The CLI uses Microsoft Entra ID authentication through azd. API-key authentication isn't supported.

Download a sample

In a writable directory, download the sample invoice with the command for your shell. Run the remaining commands from that directory.

$sampleRoot = "https://raw.githubusercontent.com/Azure-Samples"
$samplePath = "azure-ai-content-understanding-assets/main/document/invoice.pdf"
Invoke-WebRequest -Uri "$sampleRoot/$samplePath" -OutFile invoice.pdf

You can also download the sample invoice in your browser. Save it as invoice.pdf in your working directory.

Analyze a document

If you don't configure a default analyzer, the CLI uses prebuilt-layout to extract document text and layout. This command uploads the sample to your configured Azure resource and can incur charges:

azd ai cu analyze invoice.pdf

The command displays YAML front matter followed by extracted document Markdown. A shortened result looks like this:

---
mimeType: application/pdf
pages: 1
---
<!-- InputPageNumber: 1 -->

CONTOSO LTD.


# INVOICE

The terminal displays Markdown source. Tables can appear as HTML; use a Markdown preview to view saved content.

Use --analyzer <analyzer-id> (or -a) to override the default for one command. To change the saved default, run azd ai cu config set CU_DEFAULT_ANALYZER "<analyzer-id>".

Save the result

Choose Markdown for reading or JSON for the complete service response. Each command runs a new analysis that can incur charges. Neither command exports the previous result.

Markdown

To save YAML front matter and document Markdown, run:

azd ai cu analyze invoice.pdf --analyzer prebuilt-layout --output-file out.md

JSON

Use --output json (or -o json) for the complete service response:

azd ai cu analyze invoice.pdf -a prebuilt-layout -o json --output-file out.json

For either format, the terminal reports the input, status, and output path. Open out.md or out.json to inspect the saved content.

In the JSON response, document Markdown is at result.contents[0].markdown. The response also contains layout details and can include service warnings and usage. The filename extension alone doesn't select the output format.

Troubleshooting

Issue Resolution
azd ai cu isn't available Check that azd is version 1.37.0 or later and that azure.ai.content-understanding is installed.
Authentication or resource-access errors Run azd auth login and confirm that the signed-in identity has Content Understanding data-plane access on the resource.
doctor reports missing generative model defaults Continue with prebuilt-layout. Before using analyzers that require generative models, follow the CLI model setup guide.
The CU endpoint must be a resource URL, not an operation URL Use the resource endpoint, such as https://<resource-name>.services.ai.azure.com/, not a Foundry project or API operation URL.
A command uses a different resource than expected Check the effective endpoint and its source in the doctor report. A shell CU_ENDPOINT variable or an applicable azd environment can override the saved user default.
An input path does not exist or could not be resolved Run from the directory containing invoice.pdf, or pass the correct quoted path to the downloaded file.
A result file already exists Use a new output filename. Add --on-existing skip to keep the previous result without analyzing it again. Use --on-existing reanalyze only to submit another request and replace that result.

Clean up resources

This quickstart uses an existing resource and doesn't create Azure resources. If you replaced an existing user default, restore its previous value with azd ai cu config set CU_ENDPOINT "<previous-resource-endpoint>" instead of removing it.

If you saved the endpoint only for this quickstart, optionally remove it:

azd ai cu config unset CU_ENDPOINT

Reference: CLI configuration.

This command removes only the user default. It doesn't clear shell variables or settings in azd project environments.

Delete the local sample and result files if you no longer need them.

Related content

  • Last updated on