6. Developing `fox CLI`

fox CLI is primary a tool to interact with the foxBMS 2 repository through the command line. All commands must therefore be implemented as a part of it. The fox CLI implementation is found in the cli/-directory at the root of the repository.

6.1. Adding a New Command

When a new tool, i.e., a command needs to be implemented the following steps need to be done (exemplary new command my-command):

Add a new file cli/cmd_my_command/my_command_impl.py which implements the main entrance function of this command.

Add a new file cli/commands/c_my_command.py that implements the command line interface of the tool.

import click

from ..cmd_my_command import my_command_impl

# Add the new CLI commands afterwards using click, e.g., as follows:
@click.command("my-command")
@click.pass_context
def run_my_command(ctx: click.Context) -> None:
    """Add help message here"""
    # my_command_impl.do_something must return a `SubprocessResult` object
    # pass the CLI arguments to `do_something` if additional arguments
    # and/or options are needed
    ret = my_command_impl.do_something()
    ctx.exit(ret.returncode)

In cli/cli.py add the new command to the cli:

# add import of the command
from .commands.c_my_command import my_command
# add the command to the application
# ...
main.add_command(my_command)
# ...

Adhere to the following rules when using click:

Always import click as import click and do not use from click import ..., except when you are
- only using echo and/or secho or
- are testing click application using CliRunner.
Use cli/helpers/click_helpers.py for common click options (except for CAN, see next point)
When the tool uses CAN communication use the cli/helpers/fcan.py to handle the CLI arguments.
When using a verbosity flag, @verbosity_option SHALL be the second last decorator.
@click.pass_context SHALL be the last decorator.

6.2. Directory Description

6.2.1. Directories

Table 6.8 Directory description of the `cli` directory
Directory Name	Long Name	Content Description
`cmd_*`	Command_*	Actual implementation of the specific CLI command
`commands`	Commands	Implementation of the command line interface of each tool
`helpers`	Helpers	Helper functions that are used by several parts of the CLI tool
`fallback`	Fallback	Fallback for the `fox CLI` wrappers when the environment is missing
`pre-commit`	pre-commit	Scripts that are run as part of the pre-commit framework

6.2.2. Files

cli/cli.py: registers all commands.
cli/foxbms_version.py: Reads the foxBMS 2 version information from the single source of truth for the version information, the wscript at the root of the repository.

6.3. Unit Tests

Unit tests for the fox CLI shall be implemented in tests/cli.
The command line interface for each command shall be tested in tests/cli/commands/*, where each command uses its own file to tests its interface.
Each tool shall then be tested in the appropiate subdirectory, e.g., cli/cmd_etl/batetl/etl/can_decode.py is then tested in tests/cli/cmd_etl/batetl/etl/test_can_decode.py.

6. Developing fox CLI