blob: 55dd6a8d04c077301d2d85f4f227743fe3bdb51a [file] [log] [blame]
<!--
Javascript to render AIRFLOW-XXX and PR references in text
as HTML links.
Overrides extrahead block from sphinx_rtd_theme
https://www.sphinx-doc.org/en/master/templating.html
-->
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Using the Command Line Interface &mdash; Airflow Documentation</title>
<link rel="shortcut icon" href="../_static/pin_32.png"/>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/jira-links.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../_static/exampleinclude.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="UI / Screenshots" href="../ui.html" />
<link rel="prev" title="Tracking User Activity" href="tracking-user-activity.html" />
<script>
</script>
<style>
</style>
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> Airflow
</a>
<div class="version">
1.10.8
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../project.html">Project</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="../start.html">Quick Start</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial.html">Tutorial</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">How-to Guides</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="set-config.html">Setting Configuration Options</a></li>
<li class="toctree-l2"><a class="reference internal" href="initialize-database.html">Initializing a Database Backend</a></li>
<li class="toctree-l2"><a class="reference internal" href="operator/index.html">Using Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom-operator.html">Creating a custom Operator</a></li>
<li class="toctree-l2"><a class="reference internal" href="connection/index.html">Managing Connections</a></li>
<li class="toctree-l2"><a class="reference internal" href="secure-connections.html">Securing Connections</a></li>
<li class="toctree-l2"><a class="reference internal" href="secure-connections.html#rotating-encryption-keys">Rotating encryption keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="write-logs.html">Writing Logs</a></li>
<li class="toctree-l2"><a class="reference internal" href="run-behind-proxy.html">Running Airflow behind a reverse proxy</a></li>
<li class="toctree-l2"><a class="reference internal" href="run-with-systemd.html">Running Airflow with systemd</a></li>
<li class="toctree-l2"><a class="reference internal" href="run-with-upstart.html">Running Airflow with upstart</a></li>
<li class="toctree-l2"><a class="reference internal" href="use-test-config.html">Using the Test Mode Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="check-health.html">Checking Airflow Health Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="define_extra_link.html">Define an operator extra link</a></li>
<li class="toctree-l2"><a class="reference internal" href="email-config.html">Email Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracking-user-activity.html">Tracking User Activity</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Using the Command Line Interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#set-up-connection-to-a-remote-airflow-instance">Set Up connection to a remote Airflow instance</a></li>
<li class="toctree-l3"><a class="reference internal" href="#set-up-bash-zsh-completion">Set Up Bash/Zsh Completion</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-a-connection">Creating a Connection</a></li>
<li class="toctree-l3"><a class="reference internal" href="#exporting-dags-structure-to-images">Exporting DAGs structure to images</a></li>
<li class="toctree-l3"><a class="reference internal" href="#display-dags-structure">Display DAGs structure</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../ui.html">UI / Screenshots</a></li>
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../profiling.html">Data Profiling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cli.html">Command Line Interface Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scheduler.html">Scheduling &amp; Triggers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../executor/index.html">Executor</a></li>
<li class="toctree-l1"><a class="reference internal" href="../plugins.html">Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security.html">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../timezone.html">Time zones</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api.html">REST API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../integration.html">Integration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../metrics.html">Metrics</a></li>
<li class="toctree-l1"><a class="reference internal" href="../errors.html">Error Tracking</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kubernetes.html">Kubernetes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../lineage.html">Lineage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dag-serialization.html">DAG Serialization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="../best-practices.html">Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../macros.html">Macros reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../privacy_notice.html">Privacy Notice</a></li>
</ul>
<p class="caption"><span class="caption-text">References</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../_api/index.html">Python API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../configurations-ref.html">Configurations</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Airflow</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li><a href="index.html">How-to Guides</a> &raquo;</li>
<li>Using the Command Line Interface</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/howto/cli-completion.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<blockquote>
<div></div></blockquote>
<div class="section" id="using-the-command-line-interface">
<h1>Using the Command Line Interface<a class="headerlink" href="#using-the-command-line-interface" title="Permalink to this headline">ΒΆ</a></h1>
<p>This document is meant to give an overview of all common tasks while using the CLI.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For more information on CLI commands, see <a class="reference internal" href="../cli.html"><span class="doc">Command Line Interface Reference</span></a></p>
</div>
<div class="section" id="set-up-connection-to-a-remote-airflow-instance">
<h2>Set Up connection to a remote Airflow instance<a class="headerlink" href="#set-up-connection-to-a-remote-airflow-instance" title="Permalink to this headline">ΒΆ</a></h2>
<p>For some functions the CLI can use the REST API. To configure the CLI to use the API
when available configure as follows:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[cli]</span>
<span class="na">api_client</span> <span class="o">=</span> <span class="s">airflow.api.client.json_client</span>
<span class="na">endpoint_url</span> <span class="o">=</span> <span class="s">http://&lt;WEBSERVER&gt;:&lt;PORT&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="set-up-bash-zsh-completion">
<h2>Set Up Bash/Zsh Completion<a class="headerlink" href="#set-up-bash-zsh-completion" title="Permalink to this headline">ΒΆ</a></h2>
<p>When using bash (or <code class="docutils literal notranslate"><span class="pre">zsh</span></code>) as your shell, <code class="docutils literal notranslate"><span class="pre">airflow</span></code> can use
<a class="reference external" href="https://argcomplete.readthedocs.io/">argcomplete</a> for auto-completion.</p>
<p>For <a class="reference external" href="https://github.com/kislyuk/argcomplete#activating-global-completion">global activation</a> of all argcomplete enabled python applications run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo activate-global-python-argcomplete
</pre></div>
</div>
<p>For permanent (but not global) airflow activation, use:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>register-python-argcomplete airflow &gt;&gt; ~/.bashrc
</pre></div>
</div>
<p>For one-time activation of argcomplete for airflow only, use:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">eval</span> <span class="s2">&quot;</span><span class="k">$(</span>register-python-argcomplete airflow<span class="k">)</span><span class="s2">&quot;</span>
</pre></div>
</div>
<img alt="../_images/cli_completion.gif" src="../_images/cli_completion.gif" />
<p>If you’re using <code class="docutils literal notranslate"><span class="pre">zsh</span></code>, add the following to your <code class="docutils literal notranslate"><span class="pre">.zshrc</span></code>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>autoload bashcompinit
bashcompinit
<span class="nb">eval</span> <span class="s2">&quot;</span><span class="k">$(</span>register-python-argcomplete airflow<span class="k">)</span><span class="s2">&quot;</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-a-connection">
<h2>Creating a Connection<a class="headerlink" href="#creating-a-connection" title="Permalink to this headline">ΒΆ</a></h2>
<p>For information on creating connection using CLI, see <a class="reference internal" href="../cli.html#cli"><span class="std std-ref">Command Line Interface Reference</span></a></p>
</div>
<div class="section" id="exporting-dags-structure-to-images">
<h2>Exporting DAGs structure to images<a class="headerlink" href="#exporting-dags-structure-to-images" title="Permalink to this headline">ΒΆ</a></h2>
<p>The application has the functionality of saving DAG to image file. You can attach them to the documentation
for the documentation, or send another without having to send the DAG file and install the application at
the other person. However, you need to have <a class="reference external" href="https://graphviz.gitlab.io/download/">Graphviz</a> installed.</p>
<p>For example, if you want to export <code class="docutils literal notranslate"><span class="pre">example_complex</span></code> DAG then you can use the following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>airflow dag show example_complex
</pre></div>
</div>
<p>After passing the <code class="docutils literal notranslate"><span class="pre">dag_id</span></code> parameter itself, the command will print rendered DAG structure (similar to <a class="reference internal" href="../ui.html#ui-graph-view"><span class="std std-ref">Graph View</span></a>)
to the screen in the DOT format.</p>
<p>It is possible to save the file in a different format. To do this, add the switch <code class="docutils literal notranslate"><span class="pre">--save</span> <span class="pre">[filename].[format]</span></code>.
If you want to save files as PNG, you can use the following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>airflow dags show example_complex --save example_complex.png
</pre></div>
</div>
<p>An example image file may look as follow:</p>
<img alt="../_images/usage_cli_export.png" src="../_images/usage_cli_export.png" />
<p>The following file formats are supported:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">bmp</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">canon</span></code>, <code class="docutils literal notranslate"><span class="pre">dot</span></code>, <code class="docutils literal notranslate"><span class="pre">gv</span></code>, <code class="docutils literal notranslate"><span class="pre">xdot</span></code>, <code class="docutils literal notranslate"><span class="pre">xdot1.2</span></code>, <code class="docutils literal notranslate"><span class="pre">xdot1.4</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cgimage</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cmap</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">eps</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">exr</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fig</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">gd</span></code>, <code class="docutils literal notranslate"><span class="pre">gd2</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">gif</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">gtk</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ico</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">imap</span></code>, <code class="docutils literal notranslate"><span class="pre">cmapx</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">imap_np</span></code>, <code class="docutils literal notranslate"><span class="pre">cmapx_np</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ismap</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">jp2</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">jpg</span></code>, <code class="docutils literal notranslate"><span class="pre">jpeg</span></code>, <code class="docutils literal notranslate"><span class="pre">jpe</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">json</span></code>, <code class="docutils literal notranslate"><span class="pre">json0</span></code>, <code class="docutils literal notranslate"><span class="pre">dot_json</span></code>, <code class="docutils literal notranslate"><span class="pre">xdot_json</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pct</span></code>, <code class="docutils literal notranslate"><span class="pre">pict</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pdf</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pic</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">plain</span></code>, <code class="docutils literal notranslate"><span class="pre">plain-ext</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">png</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pov</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ps</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ps2</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">psd</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sgi</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">svg</span></code>, <code class="docutils literal notranslate"><span class="pre">svgz</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tga</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tif</span></code>, <code class="docutils literal notranslate"><span class="pre">tiff</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tk</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vml</span></code>, <code class="docutils literal notranslate"><span class="pre">vmlz</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vrml</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">wbmp</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">webp</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">xlib</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">x11</span></code>.</p></li>
</ul>
</div></blockquote>
<p>By default, the application search for DAGs in the directory specified in <code class="docutils literal notranslate"><span class="pre">dags_folder</span></code> option in
<code class="docutils literal notranslate"><span class="pre">[core]</span></code> section specified in the file <code class="docutils literal notranslate"><span class="pre">airflow.cfg</span></code>. You can change it with the <code class="docutils literal notranslate"><span class="pre">--subdir</span></code> switch.</p>
</div>
<div class="section" id="display-dags-structure">
<h2>Display DAGs structure<a class="headerlink" href="#display-dags-structure" title="Permalink to this headline">ΒΆ</a></h2>
<p>Sometimes you will work on DAGs that contain complex dependencies. It is helpful then to preview
the DAG to see if it is correct.</p>
<p>If you have macOS, you can use <a class="reference external" href="https://iterm2.com/">iTerm2</a> together with
the <a class="reference external" href="https://www.iterm2.com/documentation-images.html">imgcat</a> script to display the DAG structure in the
console. You also need to have <a class="reference external" href="https://graphviz.gitlab.io/download/">Graphviz</a> installed.</p>
<p>Other terminals do not support the display of high-quality graphics. You can convert the image to a text
form, but its resolution will prevent you from reading it.</p>
<p>To do this, you should use the <code class="docutils literal notranslate"><span class="pre">--imgcat</span></code> switch in the <code class="docutils literal notranslate"><span class="pre">airflow</span> <span class="pre">dags</span> <span class="pre">show</span></code> command. For example, if you
want to display <code class="docutils literal notranslate"><span class="pre">example_bash_operator</span></code> DAG then you can use the following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>airflow dag show example_bash_operator --imgcat
</pre></div>
</div>
<p>You will see a similar result as in the screenshot below.</p>
<img alt="../_images/usage_cli_imgcat.png" src="../_images/usage_cli_imgcat.png" />
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../ui.html" class="btn btn-neutral float-right" title="UI / Screenshots" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tracking-user-activity.html" class="btn btn-neutral float-left" title="Tracking User Activity" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com. Check our
<a href="../privacy_notice.html">Privacy Policy</a>
for more details.
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<!-- Theme Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-140539454-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>