# Migrate From Flask-Script to the Flask CLI

Yes. An agent rewrites a Flask-Script manage.py as Click commands on Flask's own CLI, keeps each command and flag, and shows the output of both.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-flask-script-to-flask-cli/flask-script/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Flask-Script is why many old Flask apps cannot upgrade Flask at all. Its `__init__.py` runs `from flask._compat import text_type`, a module Flask removed in 2.0, so `import flask_script` fails with `ModuleNotFoundError: No module named 'flask._compat'` on Flask 2.0.0 and on the current 3.1 release alike. The agent starts with `manage.py`, since that file is the whole surface. In an app like miguelgrinberg/flack it creates `Manager(create_app)` and registers five commands: a `Server` subclass named `runserver` that overrides `get_options` to offer host, port, debugger and reloader flags and starts the app with `socketio.run`; a `Command` subclass that passes its arguments through to `celery worker -A flack.celery`; and three `@manager.command` functions, `createdb`, `test` and `lint`. A block at the bottom sets `FLACK_CONFIG=testing` when the first argument is `test` or `lint`.

Recording a baseline comes before the port, and with a repository this old the baseline is the first obstacle. `requirements.txt` pins 2019 releases, and on a current installer the install stops at `anyjson==0.3.3` with `error in anyjson setup command: use_2to3 is invalid`, on Python 3.11 and on 3.7 alike. The agent builds a Python 3.7 environment with the build tool constrained to `setuptools<58`, leaves out the gevent, greenlet and uWSGI pins that the management commands do not import, and says so. The rest installs, and it records each command there: `createdb` creates `db.sqlite`, `runserver --help` lists six flags, `celery --version` prints Celery's version through the passthrough. It also records the oddities, because they are behaviour too. `python manage.py` with no argument dies with an `IndexError` at the line that reads `sys.argv[1]`. `lint` exits 1 when flake8 is clean and 0 when it reports problems, because the function ends with `sys.exit(lint)` on a boolean.

The port does not need a newer Flask. Flask 1.1.1, the pinned release, already ships the Click-based CLI, so the agent rewrites `manage.py` as a Click group built on `FlaskGroup` and changes no pin. Each command keeps its name. `runserver` keeps `-h`, `-p`, `-d`, `-D`, `-r` and `-R`. The Celery passthrough becomes a command with `ignore_unknown_options` and an unprocessed argument list. `createdb` accepts both `--drop-first` and the old `--drop_first`. `test` and `lint` are declared with `with_appcontext=False` and `test` sets `FLACK_CONFIG` itself, which replaces the block that inspected `sys.argv`. One detail is specific to this Flask version. Flask 1.1 hands its `ScriptInfo` object to a factory that takes exactly one required parameter, and a factory whose first parameter is a config name would then receive an object where a string belongs. This one declares two parameters with defaults, so it is called with none; the agent reads `call_factory` in the installed Flask to confirm that instead of assuming it.

The check that matters most is not about commands at all. Running any command of the new `manage.py` logs `Flask-SocketIO is Running under Werkzeug, WebSocket is not available.` `FlaskGroup` sets the environment variable `FLASK_RUN_FROM_CLI`, and Flask-SocketIO 4.2.0 reacts to it by forcing its async mode to `threading`. Under Flask-Script the same app reports `eventlet`. A port that stops at matching help text would ship a development server without WebSocket support. The agent sets the async mode explicitly where the `SocketIO` object is configured, confirms the mode reads `eventlet` again under the new entry point, and puts both readings in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace Flask-Script with Flask's built-in Click CLI in this application. Read manage.py, requirements.txt, the application factory, the README and any script that calls manage.py. List every command, its options with short and long names and defaults, and anything manage.py does before or after dispatching (environment variables, monkey patching, exit codes). Install the pinned requirements; if they do not install on a current Python, say which package fails and why, then build the oldest environment that works and say exactly how. Record the output and exit code of every command, of --help for each, and of manage.py with no arguments. Port manage.py to a click group on flask.cli.FlaskGroup without upgrading Flask or any other pin. Keep every command name, option name and exit code, including ones that look wrong; list those instead of fixing them. Check that the application object behaves the same under the new entry point: compare extension state such as the Socket.IO async mode before and after, and fix any difference the CLI introduces. Remove Flask-Script from requirements.txt. Repeat every recorded command on the new manage.py and show both outputs in the pull request. Update README commands only where they changed.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that rewrites `manage.py`, removes the `Flask-Script==2.0.5` line from `requirements.txt`, and adds one argument where the Socket.IO extension is set up. The README keeps its three documented commands, `python manage.py createdb`, `runserver` and `celery`, because they still work as written. The description lists each command with its old and new help text and exit code, the install failure and the environment the agent used instead, and the async mode before and after.

The intended differences are few. Running `manage.py` with no command now prints the list of five commands and exits 0 instead of raising. Help is Click's format, and `-?`, which Flask-Script used for help because `-h` meant host, is gone; `--help` replaces it. Everything else is meant to be identical.

Two findings are reported and left alone. The inverted exit code of `lint` is preserved, with a note that any CI job relying on it has been getting the wrong answer. And `test` fails before and after for a reason outside this job: `tests/tests.py` still imports a decorator named `async` from `flack.tasks`, a name that became a reserved word in Python 3.7 and that the application code has since renamed to `async_task`. The run shows the same failure on both sides, which is the evidence that the port did not cause it.

## Run it on every service whose manage.py imports flask_script

This is a prerequisite job: nothing else about a Flask upgrade can start until it is done, and it is the same in every service that has it. Find the repositories with a search for `flask_script` and send the body above to `POST /o/{org}/sessions` once for each, with the repository as the resource and a `request_id` that is a UUID v5 of its name. Runs beyond the key's `max_concurrent` are accepted as `queued` and start when a slot frees.

## Why run it on Rush?

Old Flask apps are hard to work on because their environments no longer build, and that is exactly the part an engineer does not want on a laptop: an end-of-life Python, a pinned build tool, packages that predate wheels. The agent assembles that environment in a sandbox that is discarded with the task, records how it built it, and the same transcript holds every command it ran there.

The Socket.IO finding shows why the run has to execute things. Nothing in the diff of `manage.py` mentions async modes; the change comes from an environment variable one library sets and another reads. It is found by loading the app both ways and printing a value, which an agent with a working environment does as a matter of course.

## Frequently asked questions

### Why do I get No module named 'flask._compat'?

Something in your environment imports Flask-Script, and Flask-Script imports a private Flask module that was removed in Flask 2.0. The package's last release still has that import, so pinning a newer Flask-Script does not help. The fix is to stop importing it, which is this migration.

### Do I have to upgrade Flask in the same change?

No, and it is better not to. Flask has had a Click command line since long before 2.0, so the port works on the Flask you already pin. The Flask upgrade becomes its own change, now unblocked.

### Will python manage.py still work, or do I have to switch to the flask command?

It still works. The agent keeps `manage.py` as the entry point by ending it with a call to the Click group, so deploy scripts and documentation that call `python manage.py createdb` do not change.

### What happens to custom Command classes with get_options?

Each becomes a function decorated with `@click.option` for every `Option` it declared, with the same short and long names and defaults. A command that captured all remaining arguments becomes a Click command that ignores unknown options and takes an unprocessed argument list, so it can still forward flags to another program.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From garyburd/redigo to gomodule/redigo](https://getrush.ai/run/migrate-garyburd-redigo-to-gomodule-redigo/redigo/)
- [Migrate a Go Test Suite From Ginkgo v1 to Ginkgo v2](https://getrush.ai/run/migrate-ginkgo-v1-to-v2/ginkgo/)
- [Replace go-bindata With go:embed in a Go Web Server](https://getrush.ai/run/migrate-go-bindata-to-embed/go-bindata/)
- [Replace mitchellh/go-homedir With os.UserHomeDir in a Go CLI](https://getrush.ai/run/migrate-go-homedir-to-os-userhomedir/go-homedir/)
- [Replace hashicorp/go-multierror With errors.Join in a Go Project](https://getrush.ai/run/migrate-go-multierror-to-errors-join/go-multierror/)
- [Migrate From go-redis v8 to v9 (github.com/redis/go-redis/v9)](https://getrush.ai/run/migrate-go-redis-v8-to-v9/go-redis/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
