CLI Reference

Commands

All HTTP method commands follow the same pattern: azd rest <method> <url> [flags]

Global Flags

These flags are available for all HTTP method commands.

Authentication

Request Configuration

Response Configuration

Advanced Options

Write-Out Variables

--write-out / -w prints a curl-style template to stderr after the request completes, so stdout stays clean for the response body. Use it in scripts and CI to capture the status code, timing, or size without parsing verbose output. The escape sequences \n and \t expand to newline and tab. Unknown%{...} tokens are left as-is.

# Print only the status code
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --write-out "%{http_code}\n" > body.json

# Status and timing on one line
azd rest get https://graph.microsoft.com/v1.0/me \
  --write-out "%{http_code} %{time_total}s %{size_download}B\n"

Response Header Checks

Use --expect-header in scripts to fail the command when a response does not include a required header or value. Header names are matched case-insensitively.

# Require a response header
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --expect-header Content-Type

# Require an exact response header value
azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --expect-header "Content-Type=application/json"

Structured Metadata File

Use --metadata-file to write a JSON sidecar with status, timing, body size, content type, and redacted response headers while keeping the response body separate.

azd rest get https://management.azure.com/subscriptions?api-version=2020-01-01 \
  --output-file body.json \
  --metadata-file metadata.json

Scope Command

Preview how azd rest would authenticate a request to a URL without sending it. The command reports the resolved authentication mode, the OAuth scope, and the matched Azure service when known. It makes no network call, and honors --scope, --no-auth, and -H headers.

# Preview the scope for a Management API URL
azd rest scope https://management.azure.com/subscriptions?api-version=2020-01-01

# See the effect of --no-auth
azd rest scope https://api.github.com/repos/Azure/azure-dev --no-auth

# Machine-readable output
azd rest scope https://graph.microsoft.com/v1.0/me --format json

Cache Command

Manage the on-disk response cache used by --cache-ttl. Cached entries are keyed by request method, final URL, and resolved scope, and are stored under the user cache directory (azd-rest/cache) with owner-only file permissions.

# Print the cache directory path
azd rest cache path

# Remove all cached responses
azd rest cache clear

Version Command

# Default output
azd rest version

# Quiet (version number only)
azd rest version --quiet

# JSON output
azd rest version --format json

Scope Detection

azd rest automatically detects the correct OAuth scope based on the URL hostname. This eliminates the need to manually specify scopes for most Azure API calls.

Supported Azure Services

Custom Scopes

For services not in the auto-detection list, provide a scope manually:

azd rest get https://api.myservice.com/data --scope https://myservice.com/.default

Pagination

When --paginate is enabled, azd rest automatically follows continuation tokens from Azure APIs. It looks for:

• nextLink in the JSON response body
• @odata.nextLink in OData responses
• Link HTTP headers with rel="next"

# Get all resources across all pages
azd rest get https://management.azure.com/subscriptions/{sub}/resources?api-version=2021-04-01 --paginate

Retry Configuration

azd rest automatically retries failed requests with exponential backoff for transient errors (5xx status codes, network errors).

# Default: 3 retries
azd rest get https://api.example.com/resource

# Custom retry count
azd rest get https://api.example.com/resource --retry 5

# Disable retries
azd rest get https://api.example.com/resource --retry 0

Exit Codes

Troubleshooting

Authentication Errors

Error: failed to get token: credential unavailable

# Ensure you're signed in to azd
azd auth login

# Or use service principal
export AZURE_CLIENT_ID="..."
export AZURE_CLIENT_SECRET="..."
export AZURE_TENANT_ID="..."

Scope Detection Issues

Error: Warning: Azure host detected but no scope found

# Manually specify scope
azd rest get https://management.azure.com/... --scope https://management.azure.com/.default

Network Errors

Error: timeout or connection refused

# Increase timeout
azd rest get https://api.example.com/resource --timeout 5m

# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

Invalid JSON Response

Error: failed to format response: invalid JSON

# Use raw format to see actual response
azd rest get https://api.example.com/resource --format raw

More Resources