Files
2026-07-17 21:00:53 +00:00

326 lines
21 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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 &#8212; 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 &#39;responder[cli,orjson]&#39;
</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 &#39;fsspec[full]&#39;
</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=&lt;addr&gt;</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=&lt;n&gt;</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=&lt;name&gt;</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=&lt;n&gt;</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">&quot;auto&quot;</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 &quot;import secrets; print(secrets.token_urlsafe(32))&quot;
</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=&quot;&lt;paste-the-generated-key&gt;&quot;
$ 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">&quot;MY_APP_SECRET&quot;</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=&quot;NOTASECRET&quot;</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 &gt; 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">
&#169;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>