pipewire/man/pipewire-cli.1.xml.in

<?xml version="1.0"?><!--*-nxml-*-->
<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>

<!--
This file is part of PipeWire.

PipeWire is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

PipeWire is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with PipeWire; if not, see <http://www.gnu.org/licenses/>.
-->

<manpage name="pipewire-cli" section="1" desc="The PipeWire Command Line Interface">

  <synopsis>
    <cmd>pipewire-cli</cmd>
  </synopsis>

  <description>
    <p>Interact with a PipeWire instance.</p>

    <p><manref name="pipewire-cli" section="1"/> starts an interactive session
    with a pipewire instance. By default, a connection is made with the local
    PipeWire instance, that of the pipewire-cli command itself.</p>

    <p>Connections to other, remote instances can be made. The current instance
      name is displayed at the prompt. Some commands operate on the current
      instance and some on the local instance.</p>

    <p>Use the 'help' command to list the available commands.</p>

  </description>

  <section name="General commands">
    <option>
      <p><opt>help</opt></p>
      <optdesc><p>Show a quick help on the commands available.</p></optdesc>
    </option>
  </section>

  <section name="Module Management">
    <p>Modules are loaded and unloaded in the local instance and can add
    functionality or objects to the local instance.</p>
    <option>
      <p><opt>load-module</opt> <arg>name</arg> [<arg>arguments...</arg>]</p>
      <optdesc><p>Load a module specified by its name and arguments. For most
	         modules it is OK to be loaded more than once.</p>
	       <p>This command returns a module variable that can be used
	       to unload the module.</p></optdesc>
    </option>

    <option>
      <p><opt>unload-module</opt> <arg>module-var</arg></p>
      <optdesc><p>Unload a module, specified either by its variable.</p></optdesc>
    </option>
  </section>

  <section name="Object Introspection">
    <option>
      <p><opt>list-objects</opt></p>
      <optdesc><p>List the objects of the current instance.</p>
      <p>Objects are listed with their id, type and version.</p></optdesc>
    </option>

    <option>
      <p><opt>info</opt> <arg>id|all</arg></p>
      <optdesc><p>Get information about a specific object or all objects.</p>
        <p>Requesting info about an object will also notify you of changes.</p>
      </optdesc>
    </option>
  </section>

  <section name="Working with remotes">
    <option>
      <p><opt>connect</opt> [<arg>remote-name</arg>]</p>
      <optdesc><p>Connect to a remote instance and make this the new current
      instance.</p><p>If no remote name is specified, a connection is made to
      the default remote instance, usually pipewire-0</p>
      <p>This command returns a remote var that can be used to disconnect or
      switch remotes</p></optdesc>
    </option>

    <option>
      <p><opt>disconnect</opt> [<arg>remote-var</arg>]</p>
      <optdesc><p>Disconnect from a remote instance.</p>
      <p>If no remote name is specified, the current instance is disconnected.
      </p></optdesc>
    </option>

    <option>
      <p><opt>list-remotes</opt></p>
      <optdesc><p>List all remote instances.</p></optdesc>
    </option>

    <option>
      <p><opt>switch-remote</opt> [<arg>remote-var</arg>]</p>
      <optdesc><p>Make the specified remote the current instance.</p>
      <p>If no remote name is specified, the local instance is made current.
      </p></optdesc>
    </option>
  </section>

  <section name="Node management">
    <option>
      <p><opt>create-node</opt> <arg>factory-name</arg> [<arg>properties...</arg>]</p>
      <optdesc><p>Create a node from a factory in the current instance.</p>
      <p>Properties are key=value pairs separated by whitespace</p>
      <p>This command returns a node variable.</p></optdesc>
    </option>

    <option>
      <p><opt>destroy-node</opt> <arg>node-var</arg></p>
      <optdesc><p>Destroy a node</p></optdesc>
    </option>

    <option>
      <p><opt>export-node</opt> <arg>node-id</arg> [<arg>remote-var</arg>]</p>
      <optdesc><p>Export a node from the local instance to the specified instance.
      When no instance is specified, the node will be exported to the current
      instance.</p></optdesc>
    </option>
  </section>

  <section name="Link management">
    <option>
      <p><opt>create-link</opt>
        <arg>node-id</arg> <arg>port-id</arg>
        <arg>node-id</arg> <arg>port-id</arg> [<arg>properties...</arg>]</p>
      <optdesc><p>Create a link between 2 nodes and ports.</p>
      <p>Port ids can be -1 to automatically select an available port.</p>
      <p>Properties are key=value pairs separated by whitespace</p>
      <p>This command returns a link variable.</p></optdesc>
    </option>

    <option>
      <p><opt>destroy-link</opt> <arg>link-var</arg></p>
      <optdesc><p>Destroy a link</p></optdesc>
    </option>
  </section>

  <section name="Examples">
    <p></p>
  </section>

  <section name="Authors">
    <p>The PipeWire Developers &lt;@PACKAGE_BUGREPORT@&gt;; PipeWire is available from <url href="@PACKAGE_URL@"/></p>
  </section>

  <section name="See also">
    <p>
      <manref name="pipewire" section="1"/>,
      <manref name="pipewire-monitor" section="1"/>,
    </p>
  </section>

</manpage>