Skip to main content
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: 
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

MistakeWhat happens
Skipping login before a private exportThe command cannot prove access to the private project.
Adding --public to a private exportYou get the public/share graph only. Remove --public for private data.
Trusting only the file extensionKeep the exported metadata next to the image and verify the file is non-empty.
Comparing public and private diagrams without contextPublic/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.
Last modified on May 17, 2026