---
title: "Using the CLI"
description: "How to use Flower on the command-line."
order: 1
---

Flower is designed to provide a friendly user experience from the
command line. The CLI has commands for both viewing and building
documentation from a Data Package's metadata. The general pattern for
how to use Flower from the CLI is:

```{.bash filename="Terminal"}
seedcase-flower COMMAND [ARGS] [OPTIONS]
```

To get started, try calling the program without any commands, arguments,
or options by typing `seedcase-flower` and pressing enter. This is the
same as invoking the `--help` flag and will show the following text:

```{.bash filename="Terminal"}
seedcase-flower
```

```{python}
#| echo: false
!uv run seedcase-flower
```

## Viewing Data Package metadata

To view the metadata of a Data Package directly in the terminal, you can
use the `view` command like so:

```{.bash filename="Terminal"}
seedcase-flower view
```

::: {.callout-tip collapse="true" icon="false"}
### Example of output

This is what the above code chunk will output, assuming there is a file
called `datapackage.json` in the working directory. Since it is designed
for the terminal, it doesn't look so nice when rendered on the website.
We show this so you have an idea of what it will look like.

```{python}
#| echo: false
# Needs root of Quarto project for path.
!uv run seedcase-flower view docs/includes/datapackage.json
```
:::

The `view` command displays the metadata in an easy to read format that
is optimized for display directly in the Terminal.

### Working with a Data Package in a custom location

By default, `view` looks for a `datapackage.json` file in the current
directory, but you can specify a different path if desired:

```{.bash filename="Terminal"}
seedcase-flower view another/directory/datapackage.json
```

It also is possible to point Flower to a Data Package that is available
online. To do this, you can provide the full URL to the remote
`datapackage.json`, e.g.

```{.bash filename="Terminal"}
seedcase-flower view https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/refs/heads/main/datapackage.json
```

::: {.callout-tip collapse="true" icon="false"}
### Example of output

This is what the above code chunk will output. Since it is designed for
the terminal, it doesn't look so nice when rendered on the website. We
show this so you have an idea of what it will look like.

```{python}
#| echo: false
!uv run seedcase-flower view https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/refs/heads/main/datapackage.json
```
:::

For Data Packages on GitHub (like for the URL used above), you can use
the `gh:` prefix as a shortcut. For example, the long URL above can be
shortened to the following:

```{.bash filename="Terminal"}
seedcase-flower view gh:seedcase-project/example-seed-beetle
```

::: {.callout-tip collapse="true" icon="false"}
### Example of output

This is what the above code chunk will output. Since it is designed for
the terminal, it doesn't look so nice when rendered on the website. We
show this so you have an idea of what it will look like.

```{python}
#| echo: false
!uv run seedcase-flower view gh:seedcase-project/example-seed-beetle
```
:::

### Styling the output

If you would like to customize the style of how the metadata is
displayed, you can use the `--style` flag. This option allows you to
format the output with any of
[the built-in styles](/docs/reference/ViewStyle.qmd):

```{.bash filename="Terminal"}
seedcase-flower view --style quarto-one-page gh:seedcase-project/example-seed-beetle
```

The `view` command can use any of
[built-in styles](/docs/reference/Style.qmd) that includes all output on
a single page. It is not compatible with multi-page styles.

::: callout-important
If you have set the `style` option in a configuration file read by
Flower, you might be confused as to why it does not have an effect when
calling `seedcase-flower view --style ...`. The reason for this is that
the `view` command by design completely ignores any configuration read
from Flower's configuration file, even those with the same name as the
options passed to `view`. You can only configure `view` via command line
flags.
:::

For more details about what you can do with `view`, see:

```{.bash filename="Terminal"}
seedcase-flower view --help
```

::: {.callout-tip collapse="true" icon="false"}
### Help output

```{python}
#| echo: false
!uv run seedcase-flower view --help
```
:::

## Building documentation from Data Package metadata

In addition to viewing metadata in the terminal, Flower converts Data
Package metadata into a set of plain text files that are more
human-friendly than the `datapackage.json`. These files can be used to
build a website for the documentation which can make your Data Package's
metadata more easily discoverable and readable. You can generate this
set of files with the `build` command:

```{.bash filename="Terminal"}
seedcase-flower build
```

::: {.callout-tip collapse="true" icon="false"}
### Example of output

This is what the above code chunk will output, assuming there is a file
called `datapackage.json` in the working directory and changing the
output directory to be `_temp/` (for website build purposes).

```{python}
#| echo: false
!uv run seedcase-flower build docs/includes/datapackage.json --output-dir _temp/
```
:::

This command generates one new file: `docs/index.qmd`. The `qmd`
extension means that this file is a
[Quarto](https://quarto.org/)-flavored Markdown file. While this is the
default text format, you can change it by specifying your own custom
templates as detailed in
[the configuration section of this guide](custom-styles.qmd). Later in
this guide, you will also see how you can generate more than one file by
using different styles with `build`.

### Changing input and output directory

By default, `build` will look for a `datapackage.json` file in the
current directory, but you can use a different source location if you
want (just like with `view`):

```{.bash filename="Terminal"}
seedcase-flower build another/directory/datapackage.json
```

To generate files in a different location, use the `--output-dir` flag
with a folder name. For example:

```{.bash filename="Terminal"}
seedcase-flower build --output-dir my-dir
```

This will generate `my-dir/index.qmd` instead of `docs/index.qmd`.

### Styling the output

Just like the `view` command, the `build` command accepts a `--style`
option. This lets you choose how the metadata are organized according to
one of the [built-in styles](/docs/reference/Style.qmd). For example, to
split the metadata for each resource in the Data Package into its own
file, you can use the `quarto-resource-listing` style:

```{.bash filename="Terminal"}
seedcase-flower build --style quarto-resource-listing
```

<!-- TODO: Update this after another style is added. -->

::: {.callout-tip collapse="true" icon="false"}
### Example of output

This is what the above code chunk will output, assuming there is a file
called `datapackage.json` in the working directory and changing the
output directory to be `_temp/` (for website build purposes).

```{python}
#| echo: false
!uv run seedcase-flower build docs/includes/datapackage.json --output-dir _temp/ --style quarto-one-page
```
:::

<!-- TODO: Add section about using `template-dir` option -->

Like the default output style is `quarto-one-page`, the
`quarto-resource-listing` style creates `docs/index.qmd` but it also
creates a separate file for the data resource in the `docs/resources/`
folder, for example `docs/resources/seed-beetle-metabolic-rate.qmd`. You
can read more about the available default styles and how to create your
own custom style in
[the configuration section of the documentation](custom-styles.qmd).
