Use SAM Doctor in under 60 seconds

INSTALL

1) Install the CLI

python -m pip install sam-doctor

You can also use pipx install sam-doctor or uvx sam-doctor demo.

For a one-off diagnosis without installing globally: uvx sam-doctor diagnose deployment.log --format markdown

Stable PyPI includes all 96 documented diagnostics, plus the shell-independent run wrapper and clipboard handoff. The standard install command is all you need.

Optional bootstrap: sam-doctor init writes a starter GitHub Actions workflow that captures a deployment failure log and runs SAM Doctor.

# Non-blocking pilot workflow
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations

# Gate on high-confidence findings after a few stable runs
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations --fail-on-confidence high --force

# Strict mode once medium-confidence findings have proven out too
sam-doctor init --deploy-command "sam deploy --no-confirm-changeset" --summary --annotations --fail-on-findings --force

If you want one workflow file for both modes, copy github-actions-workflow-two-phase-gating.yml and switch to rollout-mode: strict on demand.

Use this in Slack/Discord:

I triaged a deploy failure with SAM Doctor:
sam-doctor diagnose deployment.log --format markdown
https://sam-doctor.jacobgoldstein.dev/quickstart.html?utm_source=share_copy&utm_medium=chat

FIRST RUN

2) Diagnose a real failure excerpt

No AWS account or deployment log yet? Start with the bundled, sanitized example:

sam-doctor demo

The demo reads the tracked OIDC failure sample locally and makes no network calls. It should report exactly one finding, github.oidc.assume-role-rejected.

Save the smallest authorized excerpt you are allowed to inspect:

cat > deployment-failure.log <<'EOF'
Not authorized to perform: sts:AssumeRoleWithWebIdentity
Error: status is not authorized
EOF

sam-doctor diagnose deployment-failure.log --format markdown

Share one finding and the first safe verification step with your teammate.

For a reviewed report you can paste into a ticket or chat, copy it directly:

sam-doctor diagnose deployment-failure.log --format markdown --copy

Already copied the failure? Pipe the clipboard without creating a file:

# PowerShell on Windows
Get-Clipboard | sam-doctor diagnose - --format markdown

# macOS / Wayland Linux / X11 Linux
pbpaste | sam-doctor diagnose - --format markdown
wl-paste | sam-doctor diagnose - --format markdown
xclip -selection clipboard -o | sam-doctor diagnose - --format markdown

Review the excerpt before sharing it; redaction is helpful, not a substitute for review.

Read the project’s support boundaries before relying on a diagnosis. After the run, you can share sanitized usage feedback without sending a raw log.

Make it part of every local deploy while preserving the deploy exit code:

# Bash / zsh
set -o pipefail
sam deploy --no-confirm-changeset 2>&1 | tee deployment.log
deploy_status=${PIPESTATUS[0]}
if [ "$deploy_status" -ne 0 ]; then
  sam-doctor diagnose deployment.log --format markdown
fi
exit "$deploy_status"

# PowerShell
sam deploy --no-confirm-changeset 2>&1 | Tee-Object deployment.log
$deployStatus = $LASTEXITCODE
if ($deployStatus -ne 0) {
  sam-doctor diagnose deployment.log --format markdown
}
exit $deployStatus

These examples keep diagnosis advisory; add a confidence or findings gate only when you are ready. For a bounded rollout, follow the first-deployment pilot checklist. The CI recipe index has copyable starters for other runners.

Prefer one command without shell-specific capture glue:

sam-doctor run --log-file deployment.log --format markdown -- sam deploy --no-confirm-changeset

It streams the deploy, keeps the combined log, diagnoses only on failure, and returns the deploy exit status.

Use your command family directly:

# AWS SAM
sam-doctor diagnose deployment.log --format json --fail-on-findings

# AWS CDK
sam-doctor diagnose cdk-deploy.log --format json --fail-on-findings

# AWS CloudFormation
sam-doctor diagnose cloudformation-deploy.log --format json --fail-on-findings

CI INTEGRATION

3) Add one diagnostic step in GitHub Actions

- name: Deploy and diagnose
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    run-command: sam deploy --no-confirm-changeset
    summary: true
    annotations: true
    fail-on-findings: false

Keep authentication and environment setup in earlier steps. This single Action step captures the deploy and keeps its original exit status. Keep it non-blocking initially; when your team is comfortable with the signal quality, flip on enforcement with --fail-on-findings: true (or run sam-doctor init --fail-on-findings --force to regenerate your workflow).

The @v0 tag follows stable releases. Pin a specific release tag when reproducibility requires it.

Keep the deployment command unchanged. SAM Doctor only reads the local log and suggests the next safe verification path.

ROUTING

Use outputs to route triage

Keep CI non-blocking while still surfacing real signals:

- name: Diagnose deployment log
  if: always()
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    summary: true

- name: Open an incident thread only when needed
  if: steps.sam-doctor.outputs.has-findings == 'true'
  run: |
    echo "Findings: ${{ steps.sam-doctor.outputs.finding-count }}"

SEARCH-FIRST START

Start with your exact failure

• OIDC token failures: paste the first failing AssumeRoleWithWebIdentity block and run sam-doctor diagnose.
• Rollback noise: use the first full failure excerpt before ROLLBACK_COMPLETE messages.
• Capability requirement errors: run the first 20 lines around the CAPABILITY_IAM line through SAM Doctor.
• Container image pushes: include the registry auth and image pull failure lines in your excerpt.
• CDK/SAM package/build: point SAM Doctor at your `cdk deploy` or `sam package` excerpt for the first actionable finding.