{
  "slug": "circleci-preflight-runs-the-working-tree-through-ci-90c911c1ab64",
  "title": "circleci preflight runs the working tree through CI",
  "tools": [
    "circleci"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-10-28T15:57:37.000Z",
  "announced_at": "2026-10-28T15:57:37.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When you need CI results for local staged, unstaged, and untracked changes, run `circleci preflight run --json` and inspect failed-job events. Use `circleci preflight cleanup --force` to delete finished preflight branches without a prompt.",
    "examples": [
      "circleci preflight run --json",
      "circleci preflight cleanup --force"
    ],
    "gotchas": [
      "Version: v1.12.0",
      "Non-interactive: `--json` streams `branch_pushed`, `run_started`, `job_failed`, and `run_summary` events, one event per line.",
      "Non-interactive: Cleanup asks for confirmation; without a terminal it requires `--force`, otherwise nothing is deleted.",
      "--json: Stream events as JSON, one event per line.",
      "--force: Skip cleanup confirmation; required when cleanup would delete branches without a terminal.",
      "Prerequisite: The CLI must have a usable project slug, resolved from `--project` or the Git remote, and an authenticated CircleCI client.",
      "Snapshots include staged, unstaged, and untracked changes, minus ignored files.",
      "The snapshot is staged in an in-memory index copy and does not move refs or touch HEAD, the index, working tree, or stash.",
      "The command waits for the project's push trigger to start a run.",
      "If the default branch cannot be determined, the snapshot parent falls back to HEAD.",
      "By default, preflight stops at the first failed job; further behavior is not shown in the supplied span."
    ]
  },
  "why_it_matters": "When you need CI results for local staged, unstaged, and untracked changes before committing, run a preflight and inspect its failures.",
  "sources": [
    "https://github.com/CircleCI-Public/circleci-cli/releases/tag/v1.12.0",
    "https://github.com/CircleCI-Public/circleci-cli/pull/1889",
    "https://github.com/CircleCI-Public/circleci-cli/blob/v1.12.0/internal/cmd/root/testdata/help/circleci/preflight/run.txt",
    "https://github.com/CircleCI-Public/circleci-cli/blob/v1.12.0/internal/cmd/root/testdata/help/circleci/preflight/cleanup.txt",
    "https://github.com/CircleCI-Public/circleci-cli/blob/v1.12.0/internal/cmd/preflight/run.go"
  ],
  "rank": 0.97035,
  "review_state": "approved",
  "provenance": {
    "run_id": "daily-20261028-20",
    "verdict_id": "daily-20261028-20:daily-20261028-20-d525e4fbc2f5fb83-1:gate",
    "evidence_hash": "57d7d86c4f3c734efa1a63f8222e2aafb4ea567c16163b41a7cc00e0a8d69178"
  }
}