{
  "slug": "circleci-pipeline-run-selects-a-definition-by-name-a6281c383877",
  "title": "circleci pipeline run selects a definition by name",
  "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 starting a pipeline run by definition name, pass `--definition <name>` to `circleci pipeline run`. Use the project slug if git remote detection is unavailable, and do not combine it with `--definition-id`.",
    "examples": [
      "circleci pipeline run --project <project-slug> --definition <name>"
    ],
    "gotchas": [
      "Version: v1.12.0",
      "Non-interactive: Omitting `--definition-id` prompts interactively; `--json` outputs JSON.",
      "--definition <name>: Pipeline definition name; mutually exclusive with `--definition-id`.",
      "--project <project-slug>: Project slug; defaults to git remote.",
      "Name matching is case-insensitive and client-side; the server does not filter by name.",
      "If no definition matches, the command exits 5 and lists available definitions.",
      "If several definitions match, the command exits 2 and lists the matches.",
      "`--definition` and `--definition-id` are mutually exclusive.",
      "`project trigger list/create` continue to take only `--pipeline-definition-id`."
    ]
  },
  "why_it_matters": "When starting a pipeline run and you know the definition's name rather than its ID, select that definition by name.",
  "before": "Select a pipeline definition using `--definition-id`.",
  "sources": [
    "https://github.com/CircleCI-Public/circleci-cli/releases/tag/v1.12.0",
    "https://github.com/CircleCI-Public/circleci-cli/pull/1948",
    "https://github.com/CircleCI-Public/circleci-cli/blob/v1.12.0/internal/cmd/root/testdata/help/circleci/pipeline/run.txt"
  ],
  "rank": 0.95028,
  "review_state": "approved",
  "provenance": {
    "run_id": "daily-20261028-20",
    "verdict_id": "daily-20261028-20:daily-20261028-20-d525e4fbc2f5fb83-6:gate",
    "evidence_hash": "57d7d86c4f3c734efa1a63f8222e2aafb4ea567c16163b41a7cc00e0a8d69178"
  }
}