CLI Usage¶

azure-functions doctor validates Azure Functions Python v2 projects and reports required failures versus optional warnings.

This page is the complete command and workflow reference.

Command summary¶

azure-functions doctor [OPTIONS]

The command supports human-readable and machine-readable workflows:

local developer loops (table output)
CI gates (json + exit code)
security/code-scanning pipelines (sarif)
test-report ecosystems (junit)

Quick examples¶

Current directory:

azure-functions doctor

Specific path:

azure-functions doctor --path ./apps/orders-function

Required-only profile:

azure-functions doctor --profile minimal

JSON artifact:

azure-functions doctor --format json --output doctor.json

Verbose fix hints:

azure-functions doctor --verbose

Full option reference¶

Option	Type	Default	Description
`--path`	string	`.`	Target project directory.
`--format`	enum	`table`	Output format: `table`, `json`, `sarif`, `junit`.
`--output`	path	unset	Write output to file instead of stdout.
`--verbose`	flag	`false`	Show fix hints for non-passing checks (table mode).
`--debug`	flag	`false`	Enable debug logging for troubleshooting.
`--profile`	enum	`full` behavior	Rule profile: `minimal` or `full`.
`--rules`	path	unset	Custom rules file path.

Note

Supported output formats are currently table, json, sarif, and junit.

Exit codes¶

0: no required failures
1: one or more required failures

Warnings do not change exit code unless a required failure also exists.

Status model¶

Each item has one of:

pass
warn (optional check failed)
fail (required check failed)

Section status is fail if any required check in the section failed.

Output formats in detail¶

Table (default)¶

Best for local terminal feedback.

azure-functions doctor --format table

Includes:

grouped sections
check labels and details
summary counts
exit code line

JSON¶

Best for CI automation and post-processing.

azure-functions doctor --format json --output doctor.json

JSON includes:

metadata (tool_version, generated_at, target_path)
results (section + item diagnostics)

Contract details: JSON Output Contract

SARIF¶

Best for code scanning integrations.

azure-functions doctor --format sarif --output doctor.sarif

Generated document follows SARIF 2.1.0 structure.

JUnit¶

Best for CI systems that visualize test suites.

azure-functions doctor --format junit --output doctor-junit.xml

Each diagnostic item is represented as a test case.

Path targeting patterns¶

Single app repository:

azure-functions doctor --path .

Monorepo app path:

azure-functions doctor --path ./services/payments-function

Use explicit paths in CI to avoid accidental root-level checks.

Profile behavior¶

Default/full behavior¶

If --profile is omitted, behavior is equivalent to full.

full includes:

required checks
optional checks

Minimal profile¶

azure-functions doctor --profile minimal

minimal includes only required: true rules.

Use cases:

merge gates
low-noise deployment blockers
baseline compatibility checks

Reference: Minimal Profile

Custom rules usage¶

Run with custom rule file:

azure-functions doctor --rules ./rules/custom.json

The file must:

exist
contain valid JSON
satisfy rules.schema.json

Profiles still apply to the loaded custom rules.

Reference: Rules, Custom Rules Example

Verbose and debug modes¶

Verbose mode¶

azure-functions doctor --verbose

Shows fix: guidance for non-passing checks in table output.

Debug mode¶

azure-functions doctor --debug

Enables debug logging for diagnosing CLI internals and environment issues.

Recommended command recipes¶

Local fast check¶

azure-functions doctor --profile minimal

Local full quality sweep¶

azure-functions doctor --profile full --verbose

CI gate (required only)¶

azure-functions doctor --profile minimal --format json --output doctor.json

SARIF generation¶

azure-functions doctor --profile minimal --format sarif --output doctor.sarif

JUnit publishing¶

azure-functions doctor --profile minimal --format junit --output doctor-junit.xml

CI usage patterns¶

Fail build automatically¶

Run doctor as a normal step. Exit code already captures required failures.

Always upload artifacts¶

Capture exit code manually, upload report, then fail explicitly.

See full workflow in CI Integration Example.

Programmatic API usage¶

Public API entry point:

from azure_functions_doctor.api import run_diagnostics

Example:

from azure_functions_doctor.api import run_diagnostics


def required_failure_count(path: str) -> int:
    count = 0
    for section in run_diagnostics(path=path, profile="minimal", rules_path=None):
        for item in section["items"]:
            if item["status"] == "fail":
                count += 1
    return count

Using Doctor directly:

from pathlib import Path

from azure_functions_doctor.doctor import Doctor


def run_with_custom_rules(path: str, rules_file: str) -> list[dict]:
    doctor = Doctor(path=path, profile="full", rules_path=Path(rules_file))
    rules = doctor.load_rules()
    return doctor.run_all_checks(rules=rules)

Reference: API

Working with other tools¶

With `jq`¶

Count required failures in JSON:

jq '[.results[].items[] | select(.status=="fail")] | length' doctor.json

With Python scripts¶

import json
from pathlib import Path


def failing_labels(json_path: str) -> list[str]:
    data = json.loads(Path(json_path).read_text(encoding="utf-8"))
    labels = []
    for section in data["results"]:
        for item in section["items"]:
            if item["status"] == "fail":
                labels.append(item["label"])
    return labels

With security/scanning platforms¶

Use SARIF format and upload doctor.sarif where supported.

With test dashboards¶

Use JUnit format and publish doctor-junit.xml as a test artifact.

Troubleshooting common usage mistakes¶

Invalid path¶

Symptom: CLI returns parameter error.

Fix: Ensure --path points to an existing readable directory.

Unknown profile¶

Symptom: run fails with profile validation error.

Fix: use only minimal or full.

Unsupported format¶

Symptom: CLI rejects --format value.

Fix: choose one of table, json, sarif, junit.

Empty or invalid custom rules¶

Symptom: validation failure before checks run.

Fix: validate JSON and schema compatibility.

Operational best practices¶

Run minimal as hard CI gate
Run full in local development and scheduled quality checks
Keep JSON artifacts for failed CI runs
Prefer explicit --path in monorepos
Use --verbose for faster local remediation