<ddclass="field-odd"><p>Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></p>
<h3>Positional Arguments<aclass="headerlink"href="#Positional Arguments"title="Permalink to this headline">¶</a></h3>
<dlclass="option-list">
<dt><kbd>args</kbd></dt>
<dd></dd>
</dl>
</div>
<divclass="section"id="Named Arguments">
<h3>Named Arguments<aclass="headerlink"href="#Named Arguments"title="Permalink to this headline">¶</a></h3>
<dlclass="option-list">
<dt><kbd>-j, --json</kbd></dt>
<dd><p>Output the raw JSON response instead of the normal output.</p>
<p>Default: False</p>
</dd>
<dt><kbd>-s, --socket</kbd></dt>
<dd><p>Path to the socket file to listen on</p>
<p>Default: “/run/weldr/api.socket”</p>
</dd>
<dt><kbd>--log</kbd></dt>
<dd><p>Path to logfile (./composer-cli.log)</p>
</dd>
<dt><kbd>-a, --api</kbd></dt>
<dd><p>API Version to use (overrides server API version)</p>
</dd>
<dt><kbd>--test</kbd></dt>
<dd><p>Pass test mode to compose. 1=Mock compose with fail. 2=Mock compose with finished.</p>
<p>Default: 0</p>
</dd>
<dt><kbd>-V</kbd></dt>
<dd><p>show program’s version number and exit</p>
<p>Default: False</p>
</dd>
</dl>
</div>
<p><dlclass="simple">
<dt>compose start [–size XXXX] <BLUEPRINT><TYPE> [<IMAGE-NAME><PROVIDER><PROFILE> | <IMAGE-NAME><PROFILE.TOML>]</dt><dd><p>Start a compose using the selected blueprint and output type. –size is in MiB.
NOTE: uploading and –size are only supported by osbuild-composer.</p>
</dd>
<dt>compose start-ostree [–size XXXX] [–parent PARENT] [–ref REF] [–url url] <BLUEPRINT><TYPE> [<IMAGE-NAME><PROFILE.TOML>]</dt><dd><p>Start an ostree compose using the selected blueprint and output type. Optionally start an upload. This command
is only supported by osbuild-composer. –size is in MiB.</p>
</dd>
<dt>compose types</dt><dd><p>List the supported output types.</p>
</dd>
<dt>compose status</dt><dd><p>List the status of all running and finished composes.</p>
</dd>
<dt>compose list [waiting|running|finished|failed]</dt><dd><p>List basic information about composes.</p>
</dd>
<dt>compose log <UUID> [<SIZE>]</dt><dd><p>Show the last SIZE kB of the compose log.</p>
</dd>
<dt>compose cancel <UUID></dt><dd><p>Cancel a running compose and delete any intermediate results.</p>
</dd>
<dt>compose delete <UUID,…></dt><dd><p>Delete the listed compose results.</p>
</dd>
<dt>compose info <UUID></dt><dd><p>Show detailed information on the compose.</p>
</dd>
<dt>compose metadata <UUID></dt><dd><p>Download the metadata use to create the compose to <uuid>-metadata.tar</p>
</dd>
<dt>compose logs <UUID></dt><dd><p>Download the compose logs to <uuid>-logs.tar</p>
</dd>
<dt>compose results <UUID></dt><dd><p>Download all of the compose results; metadata, logs, and image to <uuid>.tar</p>
</dd>
<dt>compose image <UUID></dt><dd><p>Download the output image from the compose. Filename depends on the type.</p>
</dd>
<dt>blueprints list</dt><dd><p>List the names of the available blueprints.</p>
</dd>
<dt>blueprints show <BLUEPRINT,…></dt><dd><p>Display the blueprint in TOML format.</p>
</dd>
<dt>blueprints changes <BLUEPRINT,…></dt><dd><p>Display the changes for each blueprint.</p>
</dd>
<dt>blueprints diff <BLUEPRINT><FROM-COMMIT><TO-COMMIT></dt><dd><p>Display the differences between 2 versions of a blueprint.
FROM-COMMIT can be a commit hash or NEWEST
TO-COMMIT can be a commit hash, NEWEST, or WORKSPACE</p>
</dd>
<dt>blueprints save <BLUEPRINT,…></dt><dd><p>Save the blueprint to a file, <BLUEPRINT>.toml</p>
</dd>
<dt>blueprints delete <BLUEPRINT></dt><dd><p>Delete a blueprint from the server</p>
</dd>
<dt>blueprints depsolve <BLUEPRINT,…></dt><dd><p>Display the packages needed to install the blueprint.</p>
</dd>
<dt>blueprints push <BLUEPRINT></dt><dd><p>Push a blueprint TOML file to the server.</p>
</dd>
<dt>blueprints freeze <BLUEPRINT,…></dt><dd><p>Display the frozen blueprint’s modules and packages.</p>
</dd>
<dt>blueprints freeze show <BLUEPRINT,…></dt><dd><p>Display the frozen blueprint in TOML format.</p>
</dd>
<dt>blueprints freeze save <BLUEPRINT,…></dt><dd><p>Save the frozen blueprint to a file, <blueprint-name>.frozen.toml.</p>
</dd>
<dt>blueprints tag <BLUEPRINT></dt><dd><p>Tag the most recent blueprint commit as a release.</p>
</dd>
<dt>blueprints undo <BLUEPRINT><COMMIT></dt><dd><p>Undo changes to a blueprint by reverting to the selected commit.</p>
</dd>
<dt>blueprints workspace <BLUEPRINT></dt><dd><p>Push the blueprint TOML to the temporary workspace storage.</p>
</dd>
<dt>modules list</dt><dd><p>List the available modules.</p>
</dd>
<dt>projects list</dt><dd><p>List the available projects.</p>
</dd>
<dt>projects info <PROJECT,…></dt><dd><p>Show details about the listed projects.</p>
</dd>
<dt>sources list</dt><dd><p>List the available sources</p>
</dd>
<dt>sources info <SOURCE-NAME,…></dt><dd><p>Details about the source.</p>
</dd>
<dt>sources add <SOURCE.TOML></dt><dd><p>Add a package source to the server.</p>
</dd>
<dt>sources change <SOURCE.TOML></dt><dd><p>Change an existing source</p>
</dd>
<dt>sources delete <SOURCE-NAME></dt><dd><p>Delete a package source.</p>
</dd>
</dl>
<p>status show Show API server status.</p>
<p>NOTE: uploading is only available as part of the compose command
<h2>Edit a Blueprint<aclass="headerlink"href="#edit-a-blueprint"title="Permalink to this headline">¶</a></h2>
<p>Start out by listing the available blueprints using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span>
<spanclass="pre">list</span></code>, pick one and save it to the local directory by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
<spanclass="pre">blueprints</span><spanclass="pre">save</span><spanclass="pre">http-server</span></code>. If there are no blueprints available you can
copy one of the examples <aclass="reference external"href="https://github.com/weldr/lorax/tree/master/tests/pylorax/blueprints/">from the test suite</a>.</p>
<p>Edit the file (it will be saved with a .toml extension) and change the
description, add a package or module to it. Send it back to the server by
running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">push</span><spanclass="pre">http-server.toml</span></code>. You can verify that it was
saved by viewing the changelog - <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">changes</span><spanclass="pre">http-server</span></code>.</p>
</div>
<divclass="section"id="build-an-image">
<h2>Build an image<aclass="headerlink"href="#build-an-image"title="Permalink to this headline">¶</a></h2>
<p>Build a <codeclass="docutils literal notranslate"><spanclass="pre">qcow2</span></code> disk image from this blueprint by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
<spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">http-server</span><spanclass="pre">qcow2</span></code>. It will print a UUID that you can use to
keep track of the build. You can also cancel the build if needed.</p>
<p>The available types of images is displayed by <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">types</span></code>.
Currently this consists of: alibaba, ami, ext4-filesystem, google, live-iso,
<h2>Monitor the build status<aclass="headerlink"href="#monitor-the-build-status"title="Permalink to this headline">¶</a></h2>
<p>Monitor it using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">status</span></code>, which will show the status of
all the builds on the system. You can view the end of the anaconda build logs
once it is in the <codeclass="docutils literal notranslate"><spanclass="pre">RUNNING</span></code> state using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">log</span><spanclass="pre">UUID</span></code>
where UUID is the UUID returned by the start command.</p>
<p>Once the build is in the <codeclass="docutils literal notranslate"><spanclass="pre">FINISHED</span></code> state you can download the image.</p>
</div>
<divclass="section"id="download-the-image">
<h2>Download the image<aclass="headerlink"href="#download-the-image"title="Permalink to this headline">¶</a></h2>
<p>Downloading the final image is done with <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">image</span><spanclass="pre">UUID</span></code> and it will
save the qcow2 image as <codeclass="docutils literal notranslate"><spanclass="pre">UUID-disk.qcow2</span></code> which you can then use to boot a VM like this:</p>
<h2>Image Uploads<aclass="headerlink"href="#image-uploads"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span></code> can upload the images to a number of services, including AWS,
OpenStack, and vSphere. The upload can be started when the build is finished
by using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">...</span></code>. In order to access the service you need
to pass authentication details to composer-cli using a TOML file.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>This is only supported when running the <codeclass="docutils literal notranslate"><spanclass="pre">osbuild-composer</span></code> API server.</p>
</div>
</div>
<divclass="section"id="providers">
<h2>Providers<aclass="headerlink"href="#providers"title="Permalink to this headline">¶</a></h2>
<p>Providers are where the images are uploaded to. You
will need to gather some provider
specific information in order to authenticate with it. Please refer to the <codeclass="docutils literal notranslate"><spanclass="pre">osbuild-composer</span></code>
documentation for the provider specific fields. You will then create a TOML file with the
name of the provider and the settings, like this:</p>
<p>Save this into an <codeclass="docutils literal notranslate"><spanclass="pre">aws-credentials.toml</span></code> file and use it when running <codeclass="docutils literal notranslate"><spanclass="pre">start</span></code>.</p>
<divclass="section"id="aws">
<h3>AWS<aclass="headerlink"href="#aws"title="Permalink to this headline">¶</a></h3>
<p>The access key and secret key can be created by going to the
<codeclass="docutils literal notranslate"><spanclass="pre">IAM->Users->Security</span><spanclass="pre">Credentials</span></code> section and creating a new access key. The
secret key will only be shown when it is first created so make sure to record
it in a secure place. The region should be the region that you want to use the
AMI in, and the bucket can be an existing bucket, or a new one, following the
normal AWS bucket naming rules. It will be created if it doesn’t already exist.</p>
<p>When uploading the image it is first uploaded to the s3 bucket, and then
converted to an AMI. If the conversion is successful the s3 object will be
deleted. If it fails, re-trying after correcting the problem will re-use the
object if you have not deleted it in the meantime, speeding up the process.</p>
