The scenario

When a user passes an app-name reference (single positional arg matching an entry in pyproject.toml), _resolve_deployment_reference in projects/fal/src/fal/api/deploy.py builds an initial AppData from CLI flags at line 122–128, then at line 145 does:

app_data = get_app_data_from_toml(resolved_app_name)
if attach_to_deployment is not None:
    app_data = replace(app_data, attach_to_deployment=attach_to_deployment)

The assignment completely replaces the CLI-populated AppData with the TOML version. Only attach_to_deployment is subsequently re-applied via replace() — deployment_strategy, auth, reset_scale, etc. from the CLI are discarded.

Concrete proof

pyproject.toml:

[tool.fal.apps.my-app]
ref = "src/app.py::MyApp"
deployment_strategy = "recreate"

User runs: fal deploy my-app --strategy rolling --attach

Step-by-step:

1. argparse parses args.strategy = "rolling" and args.attach_to_deployment = True.
2. _deploy calls prepare_deployment(..., strategy="rolling", attach_to_deployment=True).
3. _resolve_deployment_reference builds initial AppData(deployment_strategy="rolling", attach_to_deployment=True, ...).
4. is_app_name(("my-app", None)) returns True.
5. Line 145: app_data = get_app_data_from_toml("my-app") returns AppData(deployment_strategy="recreate", attach_to_deployment=None, ...) — CLI --strategy value is gone.
6. Line 146–147: replace(app_data, attach_to_deployment=True) restores just the attach flag.
7. Final app_data.deployment_strategy == "recreate", app_data.attach_to_deployment is True.
8. _validate_attach_to_deployment (line 163) sees strategy = "recreate" and raises: "--attach/--detach only applies to rolling deployments. Use --strategy rolling or remove the attach flag."
9. The user already used --strategy rolling. The advice is a dead end — they must edit pyproject.toml.

Why this matters (and why it's a nit)

The "or remove the attach flag" half of the message is still actionable, so the user is not fully stuck. But the --strategy rolling suggestion sends them chasing a fix they already applied, which will make the underlying quirk (CLI --strategy silently ignored for app-name refs) more visible and confusing than before.

Addressing a refutation raised in verification: the objection is that this scenario requires all three conditions (app-name ref + TOML deployment_strategy = "recreate" + --attach), and that the underlying CLI-vs-TOML precedence is pre-existing behavior not introduced by this PR. Both points are accurate — this is why the finding is filed as a nit rather than blocking. What is new in this PR is the validation that surfaces the mismatch as an error, so this is the natural moment to make the message match the actual fix path.

Suggested fixes

Either would resolve it — both are follow-up polish, not merge blockers:

• (a) Update the error message to note that pyproject.toml deployment_strategy takes precedence for app-name refs, e.g.: "Use --strategy rolling (or set deployment_strategy = \"rolling\" in pyproject.toml when using an app-name reference) or remove the attach flag."
• (b) Let CLI --strategy override the TOML value for app-name refs by adding if strategy != "rolling": app_data = replace(app_data, deployment_strategy=strategy) alongside the existing attach_to_deployment override at line 146–147. This would be consistent with how the PR handles --attach itself.