---
title: "Command line"
---

This document describes the command-line interface (CLI) with
signatures, documentation, some pseudocode, and diagrams that represent
its interface along with explanations for these design decisions. It
primarily serves as a reference for us to develop from and track what
has been finished and what remains to be done.

{{< include /docs/includes/_design-status.qmd >}}

## {{< var done >}} `seedcase-flower`

`seedcase-flower` has the following signature:

``` {.bash filename="Terminal"}
seedcase-flower <COMMAND> [PARAMETERS]
```

When used on its own it will show the help message with available
commands:

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

The default behavior shows the help message to prevent accidental
execution of commands without the user intending to invoke them. Plus,
it helps as a quick way of listing what the available commands are
without having to use `--help`.

If the command is used regularly, it might be useful to set up an alias
in the Terminal for it, e.g.:

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

We intentionally use the same name as the Python package and repository,
`seedcase-flower`, to give a consistent experience when installing and
using the package. Some other projects use different names for the CLI,
e.g. `cz` for the `commitizen` package, but we believe that using the
same name reduces confusion.

There will be two commands available:

- `build`: Build the documentation from the metadata in the
  `datapackage.json` file.

- `view`: Display the `datapackage.json` metadata in a human-friendly
  way in the Terminal.

## {{< var done >}} `build`

The `build` command has the following signature, that is positional as
well as keyword-based:

``` {.bash filename="Terminal"}
seedcase-flower build [SOURCE] [STYLE] [TEMPLATE-DIR] [OUTPUT-DIR] [VERBOSE]
```

And when used, it would look like this:

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

The diagram below shows a simple flow for how the inputs and outputs
work for `build`.

```{mermaid}
%%| label: fig-cli-build-flow
%%| fig-cap: "The flow of input and output through the CLI `build` command."
%%| fig-alt: "Diagram showing the flow of input and output through the CLI `build` command. The user provides the source of the `datapackage.json` file and an optional style, which are used by the `build` command to generate output files and folders."
flowchart LR
    source("datapackage.json<br>[SOURCE: file, https,<br>gh/github]")
    config_file[".flower.toml or<br>pyproject.toml<br>[file]"]
    config_sections_file["sections.toml<br>[file]"]
    build("build")
    style_opt("--style<br>[option]")
    verbose_opt("--verbose<br>[option]")
    output_dir_opt("--output-dir<br>[option]")
    template_dir_opt("--template-dir<br>[option]")
    templates["Templates<br>[folder with<br>Jinja files]"]
    output["Output<br>[files and<br>folders]"]
    file{"file"}
    cli{"cli"}

    source --> build
    config_file --> file
    output_dir_opt --> cli
    template_dir_opt --> cli
    style_opt --> cli

    templates --> config_sections_file
    config_sections_file --> config
    cli -- "either" --> config
    file -- "or" --> config
    verbose_opt --> build
    config --> build
    build --> output
```

Configuration can be provided either as command-line arguments (as shown
in the signature) or through a configuration file. The CLI command will
first look for a configuration file named `.flower.toml` (or
`pyproject.toml`) in the current directory.

The main argument to `build` is the location of the Data Package file as
a `SOURCE` (e.g. a file path or a URL) to build the documentation from.
Flower supports the following sources:

- {{< var done >}} `file://` or a path without `file://`
- {{< var done >}} `https://`
- {{< var done >}} `gh:` or `github:`

Depending on the source given, there are different behaviours:

- If nothing is given, `build` will by default assume that `source` is a
  file path to the current directory and look for a `datapackage.json`
  file there, so the source becomes `./datapackage.json`.
- If a relative path to a folder is given, `build` will parse it to the
  absolute path and append `datapackage.json`, so that the path becomes
  `/ABSOLUTE_PATH/datapackage.json`.
- `https://` sources must point to a raw file. We won't support using
  `http://` for security reasons.
- `gh:` or `github:` sources must be in the format `gh:OWNER/REPO` or
  `github:OWNER/REPO`. It's possible to add `@REF` to the end to specify
  a Git ref, which can be a branch name, tag, or commit hash. `build`
  will parse this source to the raw `https:` of the `datapackage.json`
  file in the repository, assuming the `datapackage.json` file is in the
  root of the repository. For example:
  - `gh:seedcase-project/seedcase-flower` will parse to
    `https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/main/datapackage.json`.
  - `github:seedcase-project/example-seed-beetle@0.2.0` will parse to
    `https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/0.2.0/datapackage.json`.
  - `gh:seedcase-project/seedcase-flower@main` will parse to
    `https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/main/datapackage.json`.

<!-- TODO: Unhide when we use a `read-datapackage` package instead. -->

::: content-hidden
::: callout-note
Flower reads the `datapackage.json` file using the `read-datapackage`
package, which also outputs a structured `Properties` class.
:::
:::

::: callout-note
When Flower reads in the `datapackage.json` file, it checks whether it
comply with the Data Package specification using
[`check-datapackage`](https://check-datapackage.seedcase-project.org)
and will output an error if there are any issues.
:::

<!-- TODO: Maybe also at some point allow using `doi:` source? -->

If you want to customise the output, you need to create a `.flower.toml`
configuration file in the current directory, put the configurations in
the `pyproject.toml` for Python projects, or use the CLI options. The
design of the configuration is described in the
[Configuration settings](config.qmd) document. We don't allow
customising of the style sections via the CLI so that we can:

- Simplify the CLI implementation and avoid long commands. Especially
  considering that customising the style of output can get quite complex
  with multiple sections, templates, and output paths.
- Enforce reproducible builds by having the configuration in a file that
  can be version controlled, shared, and made visible to others, such as
  collaborators.

This also means that if the source is not a file path, we can't look for
the configuration file in the same location as the `datapackage.json`
file, even if it exists on the remote location. However, `build` will
still look for a `.flower.toml` (or `pyproject.toml`) file in the
current directory. This way, you can keep the `datapackage.json` in a
separate location from the generated documentation, which might be
useful in situations where you don't own the Data Package but you still
want to or need to generate documentation for it, e.g. when it's in a
GitHub repository not owned by you.

However, you don't need to create or have a configuration file in order
to have different styles of documentation generated. The `--style`
option allows you to quickly switch between several different built-in
styles of generated output. The behaviour of `--style` is as follows:

- If no style is given *and* no configuration file is found, it defaults
  to `quarto-one-page`.
- If a style is given *and* no configuration file is found, it uses the
  style given.
- If no style is given *and* a configuration file is found, the style
  specified in the configuration file is used.
- If a style is given *and* a configuration file is found, the style
  given in the command line overrides the style in the configuration
  file.

We override the style in the configuration file if the user specifies a
style in the CLI rather than merging the CLI option with the config file
settings. This will allow for quicker testing of different styles as
well as preventing the unintended side effects that might arise when a
style is mixed with incompatible configuration settings.

This overriding behaviour also applies to the other CLI options,
`--output-dir` and `--template-dir`; if they are used on the CLI, they
override the corresponding settings in the configuration file.

## {{< var done >}} `view`

The `view` command has the following signature, that is positional as
well as keyword-based:

``` {.bash filename="Terminal"}
seedcase-flower view [SOURCE] [STYLE]
```

And when used, it would look like this:

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

The diagram below shows a simple flow for how the inputs and outputs
work for `view`.

```{mermaid}
%%| label: fig-cli-view-flow
%%| fig-cap: "The flow of input and output through the CLI `view` command."
flowchart LR
    source("datapackage.json<br>[SOURCE: file, https,<br>gh/github]")
    view("view")
    style_opt("--style<br>[option]")
    output("Output<br>[Terminal]")

    source --> view
    style_opt --> view
    view --> output
```

In many ways, `view` works similarly to `build`, as it also takes a
source to the Data Package metadata and a `--style` option to specify
how the metadata should be displayed in the Terminal. There are a few
differences:

- No output files are generated, it only displays the metadata in a
  human-friendly way in the Terminal.
- No configuration file is used or looked for. The only way to change
  the output is to use the `--style` option with our built-in styles.

The reason we don't use a configuration file for `view` is to keep it
simple and lightweight, as it's primarily meant for quick inspection of
a Data Package's metadata. Likewise, the types of customisations that
are possible given the constraint of displaying in a Terminal are
limited compared to generating full documentation as output. This is why
we intentionally don't allow customisation outside of our built-in
styles for this command.

::: callout-tip
Want a different style for viewing the metadata? Check out our
[contribute a style](/docs/guide/contribute-style.qmd) guide.
:::
