Headless diagram image downloads

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.

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:

export CLOUDEVAL_BASE_URL="${CLOUDEVAL_BASE_URL:-https://cloudeval.ai}"
export PROJECT_ID="<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

cloudeval projects export-diagram <project-id> \
  --layout architecture|dependency \
  --format png|jpeg|svg \
  --labels all|viewport \
  --output <file> \
  [--headers-output <file>] \
  [--public] \
  [--sync-version <version>] \
  [--frontend-url <url>] \
  [--base-url <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:

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:

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:

export SYNC_VERSION="<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:

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.

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:

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.

{
  "projectId": "<project-id>",
  "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.

CLI quickstart

Automation and agents

CLI reference

Headless diagram image downloads

Why it matters

Quick example

CLI shape

Private exports

Public or shared exports

Validate export metadata

MCP tool

Security checks

Common mistakes

Tips

​Why it matters

​Quick example

​CLI shape

​Private exports

​Public or shared exports

​Validate export metadata

​MCP tool

​Security checks

​Common mistakes

​Tips

​Related pages

Why it matters

Quick example

CLI shape

Private exports

Public or shared exports

Validate export metadata

MCP tool

Security checks

Common mistakes

Tips

Related pages