<h1>Command Line Interface<aclass="headerlink"href="#command-line-interface"title="Link to this heading">¶</a></h1>
<p>Installing Flask installs the <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> script, a <aclass="reference external"href="https://click.palletsprojects.com/">Click</a> command line
interface, in your virtualenv. Executed from the terminal, this script gives
access to built-in, extension, and application-defined commands. The <codeclass="docutils literal notranslate"><spanclass="pre">--help</span></code>
option will give more information about any commands and options.</p>
<sectionid="application-discovery">
<h2>Application Discovery<aclass="headerlink"href="#application-discovery"title="Link to this heading">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command is installed by Flask, not your application; it must be
told where to find your application in order to use it. The <codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code>
option is used to specify how to load the application.</p>
<p>While <codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code> supports a variety of options for specifying your
application, most use cases should be simple. Here are the typical values:</p>
<dlclass="simple">
<dt>(nothing)</dt><dd><p>The name “app” or “wsgi” is imported (as a “.py” file, or package),
automatically detecting an app (<codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">application</span></code>) or
factory (<codeclass="docutils literal notranslate"><spanclass="pre">create_app</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">make_app</span></code>).</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">hello</span></code></dt><dd><p>The given name is imported, automatically detecting an app (<codeclass="docutils literal notranslate"><spanclass="pre">app</span></code>
or <codeclass="docutils literal notranslate"><spanclass="pre">application</span></code>) or factory (<codeclass="docutils literal notranslate"><spanclass="pre">create_app</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">make_app</span></code>).</p>
</dd>
</dl>
<hrclass="docutils"/>
<p><codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code> has three parts: an optional path that sets the current working
directory, a Python file or dotted import path, and an optional variable
name of the instance or factory. If the name is a factory, it can optionally
be followed by arguments in parentheses. The following values demonstrate these
parts:</p>
<dlclass="simple">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">src/hello</span></code></dt><dd><p>Sets the current working directory to <codeclass="docutils literal notranslate"><spanclass="pre">src</span></code> then imports <codeclass="docutils literal notranslate"><spanclass="pre">hello</span></code>.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">hello.web</span></code></dt><dd><p>Imports the path <codeclass="docutils literal notranslate"><spanclass="pre">hello.web</span></code>.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">hello:app2</span></code></dt><dd><p>Uses the <codeclass="docutils literal notranslate"><spanclass="pre">app2</span></code> Flask instance in <codeclass="docutils literal notranslate"><spanclass="pre">hello</span></code>.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">'hello:create_app("dev")'</span></code></dt><dd><p>The <codeclass="docutils literal notranslate"><spanclass="pre">create_app</span></code> factory in <codeclass="docutils literal notranslate"><spanclass="pre">hello</span></code> is called with the string <codeclass="docutils literal notranslate"><spanclass="pre">'dev'</span></code>
as the argument.</p>
</dd>
</dl>
<p>If <codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code> is not set, the command will try to import “app” or
“wsgi” (as a “.py” file, or package) and try to detect an application
instance or factory.</p>
<p>Within the given import, the command looks for an application instance named
<codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">application</span></code>, then any application instance. If no instance is
found, the command looks for a factory function named <codeclass="docutils literal notranslate"><spanclass="pre">create_app</span></code> or
<codeclass="docutils literal notranslate"><spanclass="pre">make_app</span></code> that returns an instance.</p>
<p>If parentheses follow the factory name, their contents are parsed as
Python literals and passed as arguments and keyword arguments to the
function. This means that strings must still be in quotes.</p>
</section>
<sectionid="run-the-development-server">
<h2>Run the Development Server<aclass="headerlink"href="#run-the-development-server"title="Link to this heading">¶</a></h2>
<p>The <aclass="reference internal"href="api.html#flask.cli.run_command"title="flask.cli.run_command"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">run</span></code></a> command will start the development server. It
replaces the <aclass="reference internal"href="api.html#flask.Flask.run"title="flask.Flask.run"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">Flask.run()</span></code></a> method in most cases.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span>$ flask --app hello run
* Serving Flask app "hello"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
</pre></div>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Do not use this command to run your application in production.
Only use the development server during development. The development server
is provided for convenience, but is not designed to be particularly secure,
stable, or efficient. See <aclass="reference internal"href="deploying/index.html"><spanclass="doc">Deploying to Production</span></a> for how to run in production.</p>
</div>
<p>If another program is already using port 5000, you’ll see
<codeclass="docutils literal notranslate"><spanclass="pre">OSError:</span><spanclass="pre">[Errno</span><spanclass="pre">98]</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">OSError:</span><spanclass="pre">[WinError</span><spanclass="pre">10013]</span></code> when the
server tries to start. See <aclass="reference internal"href="server.html#address-already-in-use"><spanclass="std std-ref">Address already in use</span></a> for how to
handle that.</p>
<sectionid="debug-mode">
<h3>Debug Mode<aclass="headerlink"href="#debug-mode"title="Link to this heading">¶</a></h3>
<p>In debug mode, the <codeclass="docutils literal notranslate"><spanclass="pre">flask</span><spanclass="pre">run</span></code> command will enable the interactive debugger and the
reloader by default, and make errors easier to see and debug. To enable debug mode, use
the <codeclass="docutils literal notranslate"><spanclass="pre">--debug</span></code> option.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--debug</span></code> option can also be passed to the top level <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command to enable
debug mode for any command. The following two <codeclass="docutils literal notranslate"><spanclass="pre">run</span></code> calls are equivalent.</p>
<h3>Watch and Ignore Files with the Reloader<aclass="headerlink"href="#watch-and-ignore-files-with-the-reloader"title="Link to this heading">¶</a></h3>
<p>When using debug mode, the reloader will trigger whenever your Python code or imported
modules change. The reloader can watch additional files with the <codeclass="docutils literal notranslate"><spanclass="pre">--extra-files</span></code>
option. Multiple paths are separated with <codeclass="docutils literal notranslate"><spanclass="pre">:</span></code>, or <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> on Windows.</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ flask run --extra-files file1:dirA/file2:dirB/
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
</pre></div>
</div>
<p>The reloader can also ignore files using <aclass="reference external"href="https://docs.python.org/3/library/fnmatch.html#module-fnmatch"title="(in Python v3.13)"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">fnmatch</span></code></a> patterns with the
<codeclass="docutils literal notranslate"><spanclass="pre">--exclude-patterns</span></code> option. Multiple patterns are separated with <codeclass="docutils literal notranslate"><spanclass="pre">:</span></code>, or <codeclass="docutils literal notranslate"><spanclass="pre">;</span></code> on
Windows.</p>
</section>
</section>
<sectionid="open-a-shell">
<h2>Open a Shell<aclass="headerlink"href="#open-a-shell"title="Link to this heading">¶</a></h2>
<p>To explore the data in your application, you can start an interactive Python
shell with the <aclass="reference internal"href="api.html#flask.cli.shell_command"title="flask.cli.shell_command"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">shell</span></code></a> command. An application
context will be active, and the app instance will be imported.</p>
<p>Use <aclass="reference internal"href="api.html#flask.Flask.shell_context_processor"title="flask.Flask.shell_context_processor"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">shell_context_processor()</span></code></a> to add other automatic imports.</p>
</section>
<sectionid="environment-variables-from-dotenv">
<spanid="dotenv"></span><h2>Environment Variables From dotenv<aclass="headerlink"href="#environment-variables-from-dotenv"title="Link to this heading">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command supports setting any option for any command with
environment variables. The variables are named like <codeclass="docutils literal notranslate"><spanclass="pre">FLASK_OPTION</span></code> or
<codeclass="docutils literal notranslate"><spanclass="pre">FLASK_COMMAND_OPTION</span></code>, for example <codeclass="docutils literal notranslate"><spanclass="pre">FLASK_APP</span></code> or
<p>Rather than passing options every time you run a command, or environment
variables every time you open a new terminal, you can use Flask’s dotenv
support to set environment variables automatically.</p>
<p>If <aclass="reference external"href="https://github.com/theskumar/python-dotenv#readme">python-dotenv</a> is installed, running the <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command will set
environment variables defined in the files <codeclass="docutils literal notranslate"><spanclass="pre">.env</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">.flaskenv</span></code>.
You can also specify an extra file to load with the <codeclass="docutils literal notranslate"><spanclass="pre">--env-file</span></code>
option. Dotenv files can be used to avoid having to set <codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code> or
<codeclass="docutils literal notranslate"><spanclass="pre">FLASK_APP</span></code> manually, and to set configuration using environment
variables similar to how some deployment services work.</p>
<p>Variables set on the command line are used over those set in <codeclass="file docutils literal notranslate"><spanclass="pre">.env</span></code>,
which are used over those set in <codeclass="file docutils literal notranslate"><spanclass="pre">.flaskenv</span></code>. <codeclass="file docutils literal notranslate"><spanclass="pre">.flaskenv</span></code> should be
used for public variables, such as <codeclass="docutils literal notranslate"><spanclass="pre">FLASK_APP</span></code>, while <codeclass="file docutils literal notranslate"><spanclass="pre">.env</span></code> should not
be committed to your repository so that it can set private variables.</p>
<p>Directories are scanned upwards from the directory you call <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code>
from to locate the files.</p>
<p>The files are only loaded by the <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command or calling
<aclass="reference internal"href="api.html#flask.Flask.run"title="flask.Flask.run"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">run()</span></code></a>. If you would like to load these files when running in
production, you should call <aclass="reference internal"href="api.html#flask.cli.load_dotenv"title="flask.cli.load_dotenv"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">load_dotenv()</span></code></a> manually.</p>
<sectionid="setting-command-options">
<h3>Setting Command Options<aclass="headerlink"href="#setting-command-options"title="Link to this heading">¶</a></h3>
<p>Click is configured to load default values for command options from
environment variables. The variables use the pattern
<codeclass="docutils literal notranslate"><spanclass="pre">FLASK_COMMAND_OPTION</span></code>. For example, to set the port for the run
command, instead of <codeclass="docutils literal notranslate"><spanclass="pre">flask</span><spanclass="pre">run</span><spanclass="pre">--port</span><spanclass="pre">8000</span></code>:</p>
</div><divaria-labelledby="tab-0-RmlzaA=="class="sphinx-tabs-panel group-tab"hidden="true"id="panel-0-RmlzaA=="name="RmlzaA=="role="tabpanel"tabindex="0"><divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ set -x FLASK_RUN_PORT 8000
$ flask run
* Running on http://127.0.0.1:8000/
</pre></div>
</div>
</div><divaria-labelledby="tab-0-Q01E"class="sphinx-tabs-panel group-tab"hidden="true"id="panel-0-Q01E"name="Q01E"role="tabpanel"tabindex="0"><divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>> set FLASK_RUN_PORT=8000
<p>These can be added to the <codeclass="docutils literal notranslate"><spanclass="pre">.flaskenv</span></code> file just like <codeclass="docutils literal notranslate"><spanclass="pre">FLASK_APP</span></code> to
control default command options.</p>
</section>
<sectionid="disable-dotenv">
<h3>Disable dotenv<aclass="headerlink"href="#disable-dotenv"title="Link to this heading">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command will show a message if it detects dotenv files but
</div><divaria-labelledby="tab-1-RmlzaA=="class="sphinx-tabs-panel group-tab"hidden="true"id="panel-1-RmlzaA=="name="RmlzaA=="role="tabpanel"tabindex="0"><divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ set -x FLASK_SKIP_DOTENV 1
$ flask run
</pre></div>
</div>
</div><divaria-labelledby="tab-1-Q01E"class="sphinx-tabs-panel group-tab"hidden="true"id="panel-1-Q01E"name="Q01E"role="tabpanel"tabindex="0"><divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>> set FLASK_SKIP_DOTENV=1
<p>It is preferred to use dotenv support over this, since <codeclass="file docutils literal notranslate"><spanclass="pre">.flaskenv</span></code> can be
committed to the repository so that it works automatically wherever the project
is checked out.</p>
</section>
<sectionid="custom-commands">
<h2>Custom Commands<aclass="headerlink"href="#custom-commands"title="Link to this heading">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command is implemented using <aclass="reference external"href="https://click.palletsprojects.com/">Click</a>. See that project’s
documentation for full information about writing commands.</p>
<p>This example adds the command <codeclass="docutils literal notranslate"><spanclass="pre">create-user</span></code> that takes the argument
<p>This example adds the same command, but as <codeclass="docutils literal notranslate"><spanclass="pre">user</span><spanclass="pre">create</span></code>, a command in a
group. This is useful if you want to organize multiple related commands.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span>$ flask user create demo
</pre></div>
</div>
<p>See <aclass="reference internal"href="testing.html#testing-cli"><spanclass="std std-ref">Running Commands with the CLI Runner</span></a> for an overview of how to test your custom
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ flask students create alice
</pre></div>
</div>
<p>You can alter the group name by specifying the <codeclass="docutils literal notranslate"><spanclass="pre">cli_group</span></code> parameter
when creating the <aclass="reference internal"href="api.html#flask.Blueprint"title="flask.Blueprint"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Blueprint</span></code></a> object, or later with
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ flask create alice
</pre></div>
</div>
</section>
<sectionid="application-context">
<h3>Application Context<aclass="headerlink"href="#application-context"title="Link to this heading">¶</a></h3>
<p>Commands added using the Flask app’s <aclass="reference internal"href="api.html#flask.Flask.cli"title="flask.Flask.cli"><codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">cli</span></code></a> or
will be executed with an application context pushed, so your custom
commands and parameters have access to the app and its configuration. The
<aclass="reference internal"href="api.html#flask.cli.with_appcontext"title="flask.cli.with_appcontext"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">with_appcontext()</span></code></a> decorator can be used to get the same
<h2>Plugins<aclass="headerlink"href="#plugins"title="Link to this heading">¶</a></h2>
<p>Flask will automatically load commands specified in the <codeclass="docutils literal notranslate"><spanclass="pre">flask.commands</span></code>
<aclass="reference external"href="https://packaging.python.org/tutorials/packaging-projects/#entry-points">entry point</a>. This is useful for extensions that want to add commands when
they are installed. Entry points are specified in <codeclass="file docutils literal notranslate"><spanclass="pre">pyproject.toml</span></code>:</p>
<p>Once that package is installed in the same virtualenv as your Flask project,
you can run <codeclass="docutils literal notranslate"><spanclass="pre">flask</span><spanclass="pre">my-command</span></code> to invoke the command.</p>
</section>
<sectionid="custom-scripts">
<spanid="id1"></span><h2>Custom Scripts<aclass="headerlink"href="#custom-scripts"title="Link to this heading">¶</a></h2>
<p>When you are using the app factory pattern, it may be more convenient to define
your own Click script. Instead of using <codeclass="docutils literal notranslate"><spanclass="pre">--app</span></code> and letting Flask load
your application, you can create your own Click object and export it as a
<p>Create an instance of <aclass="reference internal"href="api.html#flask.cli.FlaskGroup"title="flask.cli.FlaskGroup"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">FlaskGroup</span></code></a> and pass it the factory:</p>
<pclass="admonition-title">Errors in Custom Scripts</p>
<p>When using a custom script, if you introduce an error in your
module-level code, the reloader will fail because it can no longer
load the entry point.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code> command, being separate from your code, does not have
this issue and is recommended in most cases.</p>
</div>
</section>
<sectionid="pycharm-integration">
<h2>PyCharm Integration<aclass="headerlink"href="#pycharm-integration"title="Link to this heading">¶</a></h2>
<p>PyCharm Professional provides a special Flask run configuration to run the development
server. For the Community Edition, and for other commands besides <codeclass="docutils literal notranslate"><spanclass="pre">run</span></code>, you need to
create a custom run configuration. These instructions should be similar for any other
IDE you use.</p>
<p>In PyCharm, with your project open, click on <em>Run</em> from the menu bar and go to <em>Edit
Configurations</em>. You’ll see a screen similar to this:</p>
<imgalt="Screenshot of PyCharm run configuration."class="screenshot align-center"src="_images/pycharm-run-config.png"/>
<p>Once you create a configuration for the <codeclass="docutils literal notranslate"><spanclass="pre">flask</span><spanclass="pre">run</span></code>, you can copy and change it to
call any other command.</p>
<p>Click the <em>+ (Add New Configuration)</em> button and select <em>Python</em>. Give the configuration
a name such as “flask run”.</p>
<p>Click the <em>Script path</em> dropdown and change it to <em>Module name</em>, then input <codeclass="docutils literal notranslate"><spanclass="pre">flask</span></code>.</p>
<p>The <em>Parameters</em> field is set to the CLI command to execute along with any arguments.
This example uses <codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">hello</span><spanclass="pre">run</span><spanclass="pre">--debug</span></code>, which will run the development server in
debug mode. <codeclass="docutils literal notranslate"><spanclass="pre">--app</span><spanclass="pre">hello</span></code> should be the import or file with your Flask app.</p>
<p>If you installed your project as a package in your virtualenv, you may uncheck the
<em>PYTHONPATH</em> options. This will more accurately match how you deploy later.</p>
<p>Click <em>OK</em> to save and close the configuration. Select the configuration in the main
PyCharm window and click the play button next to it to run the server.</p>
<p>Now that you have a configuration for <codeclass="docutils literal notranslate"><spanclass="pre">flask</span><spanclass="pre">run</span></code>, you can copy that configuration and
change the <em>Parameters</em> argument to run a different CLI command.</p>
