# prefect cli migration: typer → cyclopts

## status (2026-02-04)
- PR #20549: `fast-cli-cyclopts` branch
- toggle: `PREFECT_CLI_FAST=1` env var
- native commands: `config` (view, set, unset, validate)
- everything else delegates to typer

## baseline benchmarks (CI)
all commands ~1.7s - cyclopts and typer at parity because:
1. `_get_version()` imports prefect eagerly
2. delegated commands still run through typer
3. native `config` still has heavy imports at runtime

## cyclopts patterns
- `@app.meta.default` for root callback (global options)
- `app.meta()` to invoke (not `app()`) for global option handling
- `Parameter("--flag", alias="-f")` for short flags
- `Parameter("--prompt", negative="--no-prompt")` for boolean toggles
- `app.meta.group_parameters = Group("Session Parameters")` for option grouping

## next steps for perf gains
1. lazy version lookup (only when --version invoked)
2. migrate more commands to native cyclopts
3. defer heavy imports until command execution
4. profile to find import hotspots

## key files
- `src/prefect/cli/_cyclopts/__init__.py` - main app, global options
- `src/prefect/cli/_cyclopts/config.py` - native config command
- `src/prefect/cli/__init__.py` - toggle logic
- `tests/cli/test_cyclopts_parity.py` - parity tests
- `benches/cli-bench.toml` - benchmark config