<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="flatpak-spawn">

    <refentryinfo>
        <title>flatpak spawn</title>
        <productname>flatpak</productname>

        <authorgroup>
            <author>
                <contrib>Developer</contrib>
                <firstname>Alexander</firstname>
                <surname>Larsson</surname>
                <email>alexl@redhat.com</email>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>flatpak spawn</refentrytitle>
        <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
        <refname>flatpak-spawn</refname>
        <refpurpose>Run commands in a sandbox</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
            <cmdsynopsis>
                <command>flatpak-spawn</command>
                <arg choice="opt" rep="repeat">OPTION</arg>
                <arg choice="plain">COMMAND</arg>
                <arg choice="opt" rep="repeat">ARGUMENT</arg>
            </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
        <title>Description</title>

        <para>
            Unlike other flatpak commands, <command>flatpak-spawn</command> is available
            to applications inside the sandbox. It runs <arg choice="plain">COMMAND</arg>
            outside the sandbox, either in another sandbox, or on the host.
        </para>

        <para>
            <command>flatpak-spawn</command> uses the Flatpak portal to create a copy
            the sandbox it was called from, optionally using tighter permissions and
            the latest version of the app and runtime.
        </para>

    </refsect1>

    <refsect1>
        <title>Options</title>

        <para>The following options are understood:</para>

        <variablelist>
            <varlistentry>
                <term><option>-h</option></term>
                <term><option>--help</option></term>

                <listitem><para>
                    Show help options and exit.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-v</option></term>
                <term><option>--verbose</option></term>

                <listitem><para>
                    Print debug information
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--forward-fd=FD</option></term>

                <listitem><para>
                    Forward a file descriptor
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--clear-env</option></term>

                <listitem><para>
                    Run with a clean environment
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--watch-bus</option></term>

                <listitem><para>
                    Make the spawned command exit if we do
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--env=VAR=VALUE</option></term>

                <listitem><para>
                    Set an environment variable
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--latest-version</option></term>

                <listitem><para>
                  Use the latest version of the refs that are used to set up the sandbox
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--no-network</option></term>

                <listitem><para>
                    Run without network access
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox</option></term>

                <listitem><para>
                    Run fully sandboxed.
                </para><para>
                    See the <option>--sandbox-expose</option> and
                    <option>--sandbox-expose-ro</option> options for selective file access.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox-expose=NAME</option></term>

                <listitem><para>
                  Expose read-write access to a file in the sandbox.
                </para><para>
                  Note that absolute paths or subdirectories are not allowed.
                  The files must be in the <filename>sandbox</filename> subdirectory of
                  the instance directory (i.e. <filename>~/.var/app/$APP_ID/sandbox</filename>).
                <para></para>
                  This option is useful in combination with <option>--sandbox</option> (otherwise the
                  instance directory is accessible anyway).
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--sandbox-expose-ro=NAME</option></term>

                <listitem><para>
                  Expose readonly access to a file in the sandbox.
                </para><para>
                  Note that absolute paths or subdirectories are not allowed.
                  The files must be in the <filename>sandbox</filename> subdirectory of
                  the instance directory (i.e. <filename>~/.var/app/$APP_ID/sandbox</filename>).
                <para></para>
                  This option is useful in combination with <option>--sandbox</option> (otherwise the
                  instance directory is accessible anyway).
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--host</option></term>

                <listitem><para>
                  Run the command unsandboxed on the host. This requires access to
                  the org.freedesktop.Flatpak D-Bus interface
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--directory=DIR</option></term>

                <listitem><para>
                  The working directory in which to run the command.
                </para><para>
                  Note that the given directory must exist in the sandbox or, when used in conjunction
                  with <option>--host</option>, on the host.
                </para></listitem>
            </varlistentry>

        </variablelist>
    </refsect1>

    <refsect1>
        <title>Examples</title>

        <para>
            <command>$ flatpak-spawn ls /var/run</command>
        </para>

    </refsect1>

    <refsect1>
        <title>See also</title>

        <para>
            <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>
        </para>

    </refsect1>

</refentry>
