> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudeval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Headless diagram image downloads > Download architecture and dependency diagram images from CLI, CI, or MCP agents without scraping the browser UI. Headless diagram downloads return the same diagram image a user can export from the browser. Use the CloudEval CLI when an agent needs a PNG, JPEG, or SVG file directly. Authenticate first with `cloudeval login` or `cloudeval login --headless`. Use `--machine` only when service-principal machine authentication is configured. CloudEval dependency graph that can also be exported through headless diagram image downloads ## Why it matters AI agents and CI jobs need deterministic files, not screenshots from an interactive tab. The CLI keeps the export workflow authenticated and repeatable without requiring agents to drive a browser. ## Quick example Download the private architecture and dependency diagrams for one project: ```bash theme={null} export CLOUDEVAL_BASE_URL="${CLOUDEVAL_BASE_URL:-https://cloudeval.ai}" export PROJECT_ID="" mkdir -p diagram-downloads cloudeval projects export-diagram "$PROJECT_ID" \ --layout architecture \ --format png \ --labels all \ --output diagram-downloads/architecture.png \ --headers-output diagram-downloads/architecture.headers \ --base-url "$CLOUDEVAL_BASE_URL" \ --non-interactive cloudeval projects export-diagram "$PROJECT_ID" \ --layout dependency \ --format png \ --labels all \ --output diagram-downloads/dependency.png \ --headers-output diagram-downloads/dependency.headers \ --base-url "$CLOUDEVAL_BASE_URL" \ --non-interactive ``` Expected result: * `diagram-downloads/architecture.png` * `diagram-downloads/dependency.png` * human output, `--json` `data.output`, `data.headersOutput`, and `filesWritten` report resolved absolute filesystem paths * optional headers output when you pass `--headers-output` ## CLI shape ```bash theme={null} cloudeval projects export-diagram \ --layout architecture|dependency \ --format png|jpeg|svg \ --labels all|viewport \ --output \ [--headers-output ] \ [--public] \ [--sync-version ] \ [--frontend-url ] \ [--base-url ] \ [--machine] \ [--json] \ [--non-interactive] ``` The CLI resolves the authenticated project scope from `cloudeval login`, `cloudeval login --headless`, or `--machine`. The frontend defaults to `https://cloudeval.ai`; pass `--frontend-url` only for local/dev frontends. Use `--public` only for intentionally public or shared graph bytes. ## Private exports Private CLI exports require `cloudeval login`, `cloudeval login --headless`, or `--machine`. Prefer stored login state for user workflows. PNG with all labels: ```bash theme={null} cloudeval projects export-diagram "$PROJECT_ID" \ --layout architecture \ --format png \ --labels all \ --output diagram-downloads/private-architecture.png \ --headers-output diagram-downloads/private-architecture-png.headers \ --non-interactive ``` JPEG with viewport labels: ```bash theme={null} cloudeval projects export-diagram "$PROJECT_ID" \ --layout dependency \ --format jpeg \ --labels viewport \ --output diagram-downloads/private-dependency.jpeg \ --headers-output diagram-downloads/private-dependency-jpeg.headers \ --non-interactive ``` SVG pinned to a sync snapshot: ```bash theme={null} export SYNC_VERSION="" cloudeval projects export-diagram "$PROJECT_ID" \ --layout architecture \ --format svg \ --labels all \ --sync-version "$SYNC_VERSION" \ --output diagram-downloads/private-architecture.svg \ --headers-output diagram-downloads/private-architecture-svg.headers \ --non-interactive ``` Machine-auth variant: ```bash theme={null} cloudeval projects export-diagram "$PROJECT_ID" \ --layout architecture \ --format png \ --labels all \ --output diagram-downloads/private-architecture.png \ --headers-output diagram-downloads/private-architecture-png.headers \ --machine \ --non-interactive ``` ## Public or shared exports Use `--public` only when you intentionally want public or shared graph data. It is a scope reduction: CloudEval uses only public graph data and never falls back to private project data. ```bash theme={null} cloudeval projects export-diagram "$PROJECT_ID" \ --public \ --layout dependency \ --format svg \ --labels viewport \ --output diagram-downloads/public-dependency.svg \ --headers-output diagram-downloads/public-dependency-svg.headers \ --non-interactive ``` Do not mix public mode with private exports. Keep separate output folders for private and public/share diagrams so automation does not compare the wrong scope. ## Validate export metadata When you pass `--headers-output`, keep the metadata file next to the image: ```bash theme={null} ls diagram-downloads/architecture.png diagram-downloads/architecture.headers ``` Use that metadata for audit trails and troubleshooting. Do not build automation against private response header names; prefer the CLI output envelope and saved files. ## MCP tool The CloudEval MCP server exposes the same workflow as `projects.exportDiagram`. It writes the image to `outputPath` and can optionally write response headers to `headersOutputPath`. ```json theme={null} { "projectId": "", "layout": "architecture", "format": "png", "labels": "all", "outputPath": "diagram-downloads/architecture.png", "headersOutputPath": "diagram-downloads/architecture.headers" } ``` ## Security checks These checks should be part of automation: * run `cloudeval auth status --format json` before private exports * use `--public` only for diagrams that are already safe to share * keep private and public/share outputs in separate directories * fail the job when the expected image file is missing or empty * avoid raw HTTP calls; use the CLI or MCP tool so auth and scope handling stay consistent ## Common mistakes | Mistake | What happens | | ----------------------------------------------------- | ------------------------------------------------------------------------------------- | | Skipping login before a private export | The command cannot prove access to the private project. | | Adding `--public` to a private export | You get the public/share graph only. Remove `--public` for private data. | | Trusting only the file extension | Keep the exported metadata next to the image and verify the file is non-empty. | | Comparing public and private diagrams without context | Public/share diagrams may contain fewer resources. Keep metadata next to each output. | ## Tips * Prefer `labels=all` for agent-readable diagrams. * Save headers next to each image so agents can verify provenance later. * Use CLI JSON output when scripts need structured success or failure details. * Use the web app for visual review when humans need to inspect layout details. ## Related pages * [CLI command reference](/reference/cli-command-reference) * [Agent and automation rules](/reference/agent-and-automation-rules) * [Automate evaluations with the CLI](/workflows/automate-evaluations-with-the-cli)