mirror of
https://github.com/kennethreitz/responder.git
synced 2026-10-24 05:59:12 +00:00
326 lines
21 KiB
HTML
326 lines
21 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="./">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>Command Line Interface — responder 9.2.0 documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
|
||
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
|
||
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=eb4102c5" />
|
||
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
|
||
<link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
|
||
<link rel="stylesheet" type="text/css" href="_static/design-elements.e5416f61bae5d36adc6d722a2b6f8cff.css?v=452a8e97" />
|
||
<script src="_static/documentation_options.js?v=e8b940be"></script>
|
||
<script src="_static/doctools.js?v=fd6eb6e6"></script>
|
||
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
|
||
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
|
||
<script src="_static/copybutton.js?v=fd10adb8"></script>
|
||
<script>
|
||
</script>
|
||
<script src="_static/design-tabs.js?v=f930bc37"></script>
|
||
<script src="_static/design-elements.bbdccc18c4abea9397628f9fea3d48c2.js?v=03c7770e"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Runtime Contracts" href="runtime-contracts.html" />
|
||
<link rel="prev" title="API Reference" href="api.html" />
|
||
|
||
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
||
|
||
|
||
|
||
|
||
|
||
</head><body>
|
||
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
|
||
|
||
<div class="body" role="main">
|
||
|
||
<section id="command-line-interface">
|
||
<h1>Command Line Interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h1>
|
||
<p>Responder installs a <code class="docutils literal notranslate"><span class="pre">responder</span></code> command that lets you launch
|
||
applications from the terminal. You can point it at a Python module,
|
||
a local file, or even a URL — and it will find your <code class="docutils literal notranslate"><span class="pre">API</span></code> instance
|
||
and start serving.</p>
|
||
<section id="launching-from-a-module">
|
||
<h2>Launching from a Module<a class="headerlink" href="#launching-from-a-module" title="Link to this heading">¶</a></h2>
|
||
<p>The most common way to run a Responder application in production. Use
|
||
Python’s standard dotted module path:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run acme.app
|
||
</pre></div>
|
||
</div>
|
||
<p>This imports <code class="docutils literal notranslate"><span class="pre">acme.app</span></code> and looks for an attribute called <code class="docutils literal notranslate"><span class="pre">api</span></code>
|
||
(a <code class="docutils literal notranslate"><span class="pre">responder.API</span></code> instance). It’s the same import system Python
|
||
uses everywhere — your <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> and virtual environment are
|
||
respected.</p>
|
||
</section>
|
||
<section id="launching-from-a-file">
|
||
<h2>Launching from a File<a class="headerlink" href="#launching-from-a-file" title="Link to this heading">¶</a></h2>
|
||
<p>During development, you often have a single file you want to run:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run helloworld.py
|
||
</pre></div>
|
||
</div>
|
||
<p>This loads the file directly and starts the server. Quick and easy for
|
||
prototyping and single-file applications.</p>
|
||
<p>You can test it with a simple HTTP request:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ curl http://127.0.0.1:5042/hello
|
||
hello, world!
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="launching-from-a-url">
|
||
<h2>Launching from a URL<a class="headerlink" href="#launching-from-a-url" title="Link to this heading">¶</a></h2>
|
||
<p>Responder can fetch and run a Python file from any URL — great for
|
||
demos, sharing examples, and running code from GitHub. Remote targets
|
||
require the <code class="docutils literal notranslate"><span class="pre">cli</span></code> extra:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ uv pip install 'responder[cli,orjson]'
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py
|
||
</pre></div>
|
||
</div>
|
||
<p>This also works with <code class="docutils literal notranslate"><span class="pre">github://</span></code> URLs and any filesystem protocol
|
||
supported by <a class="reference external" href="https://filesystem-spec.readthedocs.io/">fsspec</a>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run github://kennethreitz:responder@/examples/helloworld.py
|
||
</pre></div>
|
||
</div>
|
||
<p>Cloud storage is supported too — Azure Blob Storage, Google Cloud
|
||
Storage, S3, HDFS, SFTP, and more. Install <code class="docutils literal notranslate"><span class="pre">fsspec[full]</span></code> for all
|
||
protocols:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ uv pip install 'fsspec[full]'
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="custom-instance-names">
|
||
<h2>Custom Instance Names<a class="headerlink" href="#custom-instance-names" title="Link to this heading">¶</a></h2>
|
||
<p>By default, Responder looks for an attribute called <code class="docutils literal notranslate"><span class="pre">api</span></code>. If your
|
||
application uses a different name, specify it with a colon:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run acme.app:service
|
||
$ responder run myapp.py:application
|
||
</pre></div>
|
||
</div>
|
||
<p>For URLs, use a fragment:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run https://example.com/app.py#service
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="run-options">
|
||
<h2>Run Options<a class="headerlink" href="#run-options" title="Link to this heading">¶</a></h2>
|
||
<p>A few flags tune how <code class="docutils literal notranslate"><span class="pre">run</span></code> behaves:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run --host 0.0.0.0 --port 8000 acme.app
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--host=<addr></span></code> — the network address to bind to. Defaults to
|
||
<code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code> (or <code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code> when the <code class="docutils literal notranslate"><span class="pre">PORT</span></code> environment variable
|
||
is set).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--port=<n></span></code> — the port to bind to. Defaults to <code class="docutils literal notranslate"><span class="pre">5042</span></code>, or the
|
||
<code class="docutils literal notranslate"><span class="pre">PORT</span></code> environment variable when set. An explicit <code class="docutils literal notranslate"><span class="pre">--port</span></code> wins when
|
||
both are provided.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--server=<name></span></code> — the server backend: <code class="docutils literal notranslate"><span class="pre">uvicorn</span></code> (the default)
|
||
or <code class="docutils literal notranslate"><span class="pre">granian</span></code> (requires the <code class="docutils literal notranslate"><span class="pre">server</span></code> extra).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--reload</span></code> — restart the server automatically when source files
|
||
change. Development only. Reload mode hands your app to uvicorn’s
|
||
reloader, which must re-import it, so it requires a module target
|
||
such as <code class="docutils literal notranslate"><span class="pre">acme.app:api</span></code> (file paths and URLs won’t work) and the
|
||
default uvicorn backend.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--debug</span></code> — turn on debug mode with verbose, debug-level logging.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--limit-max-requests=<n></span></code> — serve at most <code class="docutils literal notranslate"><span class="pre">n</span></code> requests, then exit.
|
||
Handy for smoke tests and short-lived runs.</p></li>
|
||
</ul>
|
||
<p>During development, the two usually go together:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run --reload --port 8000 acme.app:api
|
||
</pre></div>
|
||
</div>
|
||
<p>To check the version or list every command, run:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder --version
|
||
$ responder --help
|
||
</pre></div>
|
||
</div>
|
||
<p>Running bare <code class="docutils literal notranslate"><span class="pre">responder</span></code> with no subcommand prints the usage summary
|
||
and exits with a non-zero status.</p>
|
||
</section>
|
||
<section id="environment-variables">
|
||
<h2>Environment Variables<a class="headerlink" href="#environment-variables" title="Link to this heading">¶</a></h2>
|
||
<p>Responder reads two environment variables on its own — convenient when
|
||
you launch through the CLI and would rather not touch application code:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">PORT</span></code> — when set, the server binds to <code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code> on this port.
|
||
This is how cloud platforms like Fly.io, Railway, and Heroku inject
|
||
the listen port.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">RESPONDER_SECRET_KEY</span></code> — the signing key for cookie sessions.</p></li>
|
||
</ul>
|
||
<p>Set <code class="docutils literal notranslate"><span class="pre">RESPONDER_SECRET_KEY</span></code> for any real deployment. If it’s unset (and
|
||
sessions are left at their <code class="docutils literal notranslate"><span class="pre">"auto"</span></code> default), Responder mints a random
|
||
key per process and logs a warning. That’s fine for a quick demo, but
|
||
every worker ends up with a different key, so signed session cookies stop
|
||
validating across workers and restarts — and users get logged out.</p>
|
||
<p>Generate a stable key with the canonical one-liner:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||
</pre></div>
|
||
</div>
|
||
<p>then export it and run:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ export RESPONDER_SECRET_KEY="<paste-the-generated-key>"
|
||
$ responder run acme.app
|
||
</pre></div>
|
||
</div>
|
||
<p>No code change is needed. To read a differently-named variable instead,
|
||
pass it explicitly when you construct the app:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
|
||
<span class="n">api</span> <span class="o">=</span> <span class="n">responder</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="n">secret_key</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">"MY_APP_SECRET"</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The old public default <code class="docutils literal notranslate"><span class="pre">secret_key="NOTASECRET"</span></code> is now rejected
|
||
and raises <code class="docutils literal notranslate"><span class="pre">SessionConfigError</span></code>. See <a class="reference internal" href="deployment.html"><span class="doc">Deployment</span></a> for the
|
||
full production checklist and <a class="reference internal" href="guide-config.html"><span class="doc">Configuration</span></a> for the rest of
|
||
the session settings.</p>
|
||
</div>
|
||
</section>
|
||
<section id="building-frontend-assets">
|
||
<h2>Building Frontend Assets<a class="headerlink" href="#building-frontend-assets" title="Link to this heading">¶</a></h2>
|
||
<p>If your project includes a JavaScript frontend with a <code class="docutils literal notranslate"><span class="pre">package.json</span></code>,
|
||
the <code class="docutils literal notranslate"><span class="pre">build</span></code> subcommand runs <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">build</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder build
|
||
$ responder build /path/to/frontend
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="generating-a-client">
|
||
<h2>Generating a Client<a class="headerlink" href="#generating-a-client" title="Link to this heading">¶</a></h2>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">client</span></code> subcommand generates an API client from your app’s OpenAPI
|
||
schema, using the same import target as <code class="docutils literal notranslate"><span class="pre">run</span></code>. By default it prints a
|
||
Python client to stdout:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder client acme.app:api > clients/service.py
|
||
</pre></div>
|
||
</div>
|
||
<p>Use <code class="docutils literal notranslate"><span class="pre">--lang</span></code> for another ecosystem (<code class="docutils literal notranslate"><span class="pre">python</span></code>, <code class="docutils literal notranslate"><span class="pre">javascript</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">typescript</span></code>, <code class="docutils literal notranslate"><span class="pre">ruby</span></code>, or <code class="docutils literal notranslate"><span class="pre">php</span></code>), <code class="docutils literal notranslate"><span class="pre">--class-name</span></code> to name the class, and
|
||
<code class="docutils literal notranslate"><span class="pre">--output</span></code> / <code class="docutils literal notranslate"><span class="pre">-o</span></code> to write a file instead of stdout:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder client --lang typescript --class-name ServiceClient \
|
||
-o clients/service.ts acme.app:api
|
||
</pre></div>
|
||
</div>
|
||
<p>The generated clients are dependency-free and typed where your OpenAPI schema
|
||
has models. See <a class="reference internal" href="clientgen.html"><span class="doc">Generated Clients</span></a> for the full feature set and the
|
||
<code class="docutils literal notranslate"><span class="pre">api.generate_client(...)</span></code> equivalent.</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper"><p class="logo">
|
||
<a href="index.html">
|
||
<img class="logo" src="_static/responder.png" />
|
||
</a>
|
||
</p>
|
||
<p>
|
||
<strong>Responder</strong> — a familiar HTTP service framework for Python.
|
||
<br />
|
||
<small>v9.2.0</small>
|
||
</p>
|
||
<h3>Useful Links</h3>
|
||
<ul>
|
||
<li><a href="https://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
|
||
<li><a href="https://pypi.org/project/responder/">Responder @ PyPI</a></li>
|
||
<li><a href="https://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
|
||
</ul><h3>Navigation</h3>
|
||
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tour.html">Feature Tour</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="routers.html">Composing Apps with Routers</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="guide-config.html">Configuration</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="clientgen.html">Generated Clients</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="deployment.html">Deployment</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
|
||
</ul>
|
||
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-rest.html">Building a REST API</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-sqlalchemy.html">Using SQLAlchemy</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-auth.html">Authentication</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-websockets.html">WebSocket Tutorial</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-middleware.html">Writing Middleware</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial-flask.html">Migrating from Flask</a></li>
|
||
</ul>
|
||
<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
|
||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Command Line Interface</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="#launching-from-a-module">Launching from a Module</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#launching-from-a-file">Launching from a File</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#launching-from-a-url">Launching from a URL</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#custom-instance-names">Custom Instance Names</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#run-options">Run Options</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#environment-variables">Environment Variables</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#building-frontend-assets">Building Frontend Assets</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#generating-a-client">Generating a Client</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="runtime-contracts.html">Runtime Contracts</a></li>
|
||
</ul>
|
||
<p class="caption" role="heading"><span class="caption-text">Project</span></p>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="changes.html">Changelog</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="migration-v9.html">Migrating to v9</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="migration-v8.html">Migrating to v8</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="migration-v7.html">Migrating to v7</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="migration-v6.html">Migrating to v6</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="migration-v5.html">Migrating to v5</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="sandbox.html">Sandbox</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="backlog.html">Backlog</a></li>
|
||
</ul>
|
||
|
||
<div class="relations">
|
||
<h3>Related Topics</h3>
|
||
<ul>
|
||
<li><a href="index.html">Documentation overview</a><ul>
|
||
<li>Previous: <a href="api.html" title="previous chapter">API Reference</a></li>
|
||
<li>Next: <a href="runtime-contracts.html" title="next chapter">Runtime Contracts</a></li>
|
||
</ul></li>
|
||
</ul>
|
||
</div>
|
||
<search id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</search>
|
||
<script>document.getElementById('searchbox').style.display = "block"</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="footer">
|
||
©2018-2026, Kenneth Reitz.
|
||
|
||
|
|
||
<a href="_sources/cli.rst.txt"
|
||
rel="nofollow">Page source</a>
|
||
</div>
|
||
|
||
|
||
<a href="https://github.com/kennethreitz/responder" class="github">
|
||
<img src="_static/forkme_right_darkblue.png" alt="Fork me on GitHub" class="github"/>
|
||
</a>
|
||
|
||
|
||
|
||
</body>
|
||
</html> |