Command line

This document describes the command-line interface (CLI) as a development reference and to track implementation status.

We use symbols to indicate the status of implementation (see table below). For planned or in-progress work, we might include signatures, docstrings, and pseudocode to clarify the design. Once the interface is implemented, these are replaced by links to the reference documentation.

A table showing the symbols used to indicate the status of interface components, along with their descriptions.
Status Description

Interface that has been implemented.

Interface that is currently being worked on.

Interface that is planned, but isn’t being worked on currently.

seedcase-flower

seedcase-flower has the following signature:

Terminal
seedcase-flower <COMMAND> [PARAMETERS]

When used on its own, seedcase-flower shows the help message as a shorthand for --help:

Terminal
seedcase-flower
Note

As a convenience, we provide the command flower as a shorthand for seedcase-flower. It can be used in place of seedcase-flower in all instances.

seedcase-flower has two commands, build and view, which are described in the following sections.

build

The build command builds documentation files from the metadata in the datapackage.json file. It has the following signature that is positional as well as keyword-based:

Terminal
seedcase-flower build [SOURCE] [STYLE] [TEMPLATE-DIR] [OUTPUT-DIR] [VERBOSE]

For example:

Terminal
seedcase-flower build SOURCE --style STYLE

The diagram below shows the flow of inputs and outputs for build:

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
Figure 1: The flow of input and output through the CLI build command.

Configuration can be provided as command-line arguments or through a configuration file. build first looks for .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:

  • file:// or a path without file://
  • https://
  • gh: or github:

build’s behaviour depends on the SOURCE format given:

  • If nothing is given, build by default assumes that source is a file path to the current directory and looks for a datapackage.json file there, corresponding to ./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 specify a Git ref, like 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.
Note

When Flower reads in the datapackage.json file, it checks whether it complies with the Data Package specification using check-datapackage and will output an error if there are any issues.

Output can be customised via .flower.toml, pyproject.toml, or CLI options. The design of the configuration is described in Configuration settings. We don’t allow customising the sections via the CLI to:

  • Simplify the CLI implementation
  • Avoid long commands. 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 and shared.

build always looks for .flower.toml (or pyproject.toml) in the current directory, not the source location. This means the datapackage.json can live elsewhere, which is useful when you don’t own the Data Package, e.g. when it’s in an external GitHub repository.

A configuration file isn’t required; the --style option lets you switch between several built-in styles:

Tip

For examples of the built-in style, see the Examples page.

The behaviour of --style is as follows:

  • If no style is given and no configuration file is found, the default style is quarto-one-page.
  • If a style is given and no configuration file is found, the style given is used.
  • 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.

The CLI options --style, --output-dir, and --template-dir override the corresponding configuration file settings, which allows for easier testing of the styles and prevents unintended side effects from mixing incompatible configurations.

view

The view command displays the datapackage.json metadata in a human-friendly way in the terminal. It has the following signature that is positional as well as keyword-based:

Terminal
seedcase-flower view [SOURCE] [STYLE]

For example:

Terminal
seedcase-flower view SOURCE --style STYLE

The diagram below shows the flow of inputs and outputs for view.

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
Figure 2: The flow of input and output through the CLI view command.

view takes a SOURCE and --style argument like build, with two differences:

  • No output files are generated—view only displays the metadata in the terminal.
  • No configuration file is used. The only way to change the output is via --style with one of the built-in styles.

view intentionally has no configuration file support; it’s meant for quick, lightweight inspection of a Data Package’s metadata and terminal display also limits customisation options.

Tip

Want a different style for viewing the metadata? Check out our contribute a style guide.