CLI

sereto.cli.cli

clean(ctx, generated)

Delete auxilary files created during the PDF build.

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.option(
    "--generated",
    is_flag=True,
    default=False,
    help="Also delete generated layout files (layouts/generated).",
)
@click.pass_obj
def clean(ctx: Project, generated: bool) -> None:
    """Delete auxilary files created during the PDF build."""
    if (build_dir := ctx.path / ".build").is_dir():
        shutil.rmtree(build_dir)

    generated_dir = ctx.path / "layouts" / "generated"
    if generated and generated_dir.is_dir():
        shutil.rmtree(generated_dir)

cli(ctx, log_level)

Security Reporting Tool.

This tool provides various commands for managing and generating security reports.

Source code in sereto/cli/cli.py

@click.group(cls=AliasedGroup, context_settings={"help_option_names": ["-h", "--help"]})
@click.version_option(version=importlib.metadata.version("sereto"))
@click.option(
    "--log-level",
    "log_level",
    type=click.Choice([level.value for level in LogLevel], case_sensitive=False),
    show_default=True,
    help="Set log verbosity for terminal output.",
)
@click.pass_context
def cli(ctx: click.Context, log_level: LogLevel | None) -> None:
    """Security Reporting Tool.

    This tool provides various commands for managing and generating security reports.
    """
    if log_level is not None or not is_logging_configured():
        setup_logging(log_level)

    ctx.obj = Project()

cli_pdf_finding_group(ctx, target_selector, finding_group_selector, converter, renderer, template, version, all)

Generate a finding group PDF.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
target_selector	int | str | None	The target for which the finding group is being generated.	required
finding_group_selector	int | str | None	The finding group to be generated.	required
converter	str | None	The recipe for converting the findings.	required
renderer	str | None	The recipe for building TeX.	required
template	str	The template for the finding group.	required
version	ProjectVersion | None	The version of the configuration to use. If None, the last version is used.	required
all	bool	Flag to render all finding groups (exclusive with selectors).	required

Source code in sereto/cli/cli.py

@pdf.command(name="finding-group")
@handle_exceptions
@click.option("-ts", "--target-selector", help="Target selector.")
@click.option("-fs", "--finding-group-selector", help="Finding group selector.")
@click.option("-c", "--converter", help="Convert finding recipe")
@click.option("-r", "--renderer", help="Build TeX finding recipe")
@click.option("-t", "--template", default="finding_group", help="Template for the finding group.")
@click.option("-v", "--version", help="Use config at specific version, e.g. 'v1.0'.")
@click.option(
    "-a",
    "--all",
    is_flag=True,
    default=False,
    help="Render all finding groups (mutually exclusive with --target-selector / --finding-group-selector).",
)
@click.pass_obj
@validate_call
def cli_pdf_finding_group(
    ctx: Project,
    target_selector: int | str | None,
    finding_group_selector: int | str | None,
    converter: str | None,
    renderer: str | None,
    template: str,
    version: ProjectVersion | None,
    all: bool,
) -> None:
    """Generate a finding group PDF.\f

    Args:
        ctx: Project's representation.
        target_selector: The target for which the finding group is being generated.
        finding_group_selector: The finding group to be generated.
        converter: The recipe for converting the findings.
        renderer: The recipe for building TeX.
        template: The template for the finding group.
        version: The version of the configuration to use. If None, the last version is used.
        all: Flag to render all finding groups (exclusive with selectors).
    """
    # Exclusivity checks
    if all and (target_selector is not None or finding_group_selector is not None):
        raise SeretoValueError("--all cannot be used together with --target-selector or --finding-group-selector")

    if all:
        generate_all_pdf_finding_groups(
            project=ctx, template=template, converter=converter, renderer=renderer, version=version
        )
    else:
        find_and_generate_pdf_finding_group(
            project=ctx,
            template=template,
            target_selector=target_selector,
            finding_group_selector=finding_group_selector,
            converter=converter,
            renderer=renderer,
            version=version,
        )

cli_pdf_report(ctx, convert_recipe, report_recipe, template, version)

Generate a report PDF.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
convert_recipe	str | None	The recipe for converting the findings.	required
report_recipe	str | None	The recipe for building the TeX report.	required
template	str	The template for the report.	required
version	ProjectVersion | None	The version of the configuration to use. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@pdf.command(name="report")
@handle_exceptions
@click.option("-c", "--convert-recipe", help="Convert finding recipe.")
@click.option("-r", "--report-recipe", help="Build TeX report recipe.")
@click.option("-t", "--template", default="report", help="Template for the report.")
@click.option("-v", "--version", help="Use config at specific version, e.g. 'v1.0'.")
# @click.option("-l", "--layout", help="Alternative layout for the report.")
@click.pass_obj
@validate_call
def cli_pdf_report(
    ctx: Project,
    convert_recipe: str | None,
    report_recipe: str | None,
    template: str,
    version: ProjectVersion | None,
) -> None:
    """Generate a report PDF.\f

    Args:
        ctx: Project's representation.
        convert_recipe: The recipe for converting the findings.
        report_recipe: The recipe for building the TeX report.
        template: The template for the report.
        version: The version of the configuration to use. If None, the last version is used.
    """
    # Create report PDF
    report_pdf = generate_pdf_report(
        project=ctx, template=template, report_recipe=report_recipe, convert_recipe=convert_recipe, version=version
    )

    # Create and attach source archive
    archive = create_source_archive(project_path=ctx.path, config=ctx.config)
    embed_attachment_to_pdf(attachment=archive, pdf=report_pdf, name=f"source{archive.suffix}", keep_original=False)

cli_pdf_sow(ctx, sow_recipe, version)

Generate a Statement of Work (SoW) PDF.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
sow_recipe	str | None	The recipe for building the TeX SoW.	required
version	ProjectVersion | None	The version of the configuration to use. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@pdf.command(name="sow")
@handle_exceptions
@click.option("-r", "--sow-recipe", help="Build TeX recipe")
@click.option("-v", "--version", help="Use config at specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def cli_pdf_sow(ctx: Project, sow_recipe: str | None, version: ProjectVersion | None) -> None:
    """Generate a Statement of Work (SoW) PDF.\f

    Args:
        ctx: Project's representation.
        sow_recipe: The recipe for building the TeX SoW.
        version: The version of the configuration to use. If None, the last version is used.
    """
    generate_pdf_sow(project=ctx, sow_recipe=sow_recipe, version=version)

cli_pdf_target(ctx, target_selector, target_recipe, convert_recipe, template, version)

Generate a target PDF.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
target_selector	int | str | None	The target for which the PDF is being generated.	required
target_recipe	str | None	The recipe for building the TeX target.	required
convert_recipe	str | None	The recipe for converting the findings.	required
template	str	The template for the target.	required
version	ProjectVersion | None	The version of the configuration to use. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@pdf.command(name="target")
@handle_exceptions
@click.option("-ts", "--target-selector", help="Target selector.")
@click.option("-c", "--convert-recipe", help="Convert finding recipe")
@click.option("-r", "--target-recipe", help="Build TeX target recipe")
@click.option("-t", "--template", default="target", help="Template for the target.")
@click.option("-v", "--version", help="Use config at specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def cli_pdf_target(
    ctx: Project,
    target_selector: int | str | None,
    target_recipe: str | None,
    convert_recipe: str | None,
    template: str,
    version: ProjectVersion | None,
) -> None:
    """Generate a target PDF.\f

    Args:
        ctx: Project's representation.
        target_selector: The target for which the PDF is being generated.
        target_recipe: The recipe for building the TeX target.
        convert_recipe: The recipe for converting the findings.
        template: The template for the target.
        version: The version of the configuration to use. If None, the last version is used.
    """
    generate_pdf_target(
        project=ctx,
        template=template,
        target_selector=target_selector,
        target_recipe=target_recipe,
        convert_recipe=convert_recipe,
        version=version,
    )

config()

Project's configuration.

This group of commands allows you to manage the configuration of a project.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def config() -> None:
    """Project's configuration.

    This group of commands allows you to manage the configuration of a project.
    """

config_dates()

Configuration of dates.

This group of commands allows you to manage the dates configuration of a project.

Source code in sereto/cli/cli.py

@config.group(cls=AliasedGroup, name="dates")
def config_dates() -> None:
    """Configuration of dates.

    This group of commands allows you to manage the dates configuration of a project.
    """

config_dates_add(ctx, version)

Add date to the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to add the date to. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_dates.command(name="add")
@handle_exceptions
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_dates_add(ctx: Project, version: ProjectVersion | None) -> None:
    """Add date to the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to add the date to. If None, the last version is used.
    """
    add_dates_config(config=ctx.config, version=version)

config_dates_delete(ctx, index, version)

Delete date from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
index	int	The index of the date to be deleted. You can obtain the index by running sereto config dates show.	required
version	ProjectVersion | None	The specific version of the configuration to delete the date from. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_dates.command(name="delete")
@handle_exceptions
@click.option("-i", "--index", required=True, type=int, help="Date index to be deleted.")
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_dates_delete(ctx: Project, index: int, version: ProjectVersion | None) -> None:
    """Delete date from the project's configuration.\f

    Args:
        ctx: Project's representation.
        index: The index of the date to be deleted. You can obtain the index by running `sereto config dates show`.
        version: The specific version of the configuration to delete the date from. If None, the last version is used.
    """
    if version is None:
        version = ctx.config.last_version

    # Delete the date from the configuration
    ctx.config.at_version(version).delete_date(index=index)

    # Write the configuration
    ctx.config.save()

config_dates_show(ctx, version, all, output_format)

Show dates from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to show dates from. If None, the last version is used.	required
all	bool	Flag to show dates from all versions of the configuration.	required
output_format	OutputFormat	The output format for displaying the dates.	required

Source code in sereto/cli/cli.py

@config_dates.command(name="show")
@handle_exceptions
@click.option("-v", "--version", help="Show dates from specific version, e.g. 'v1.0'.")
@click.option(
    "-a",
    "--all",
    is_flag=True,
    show_default=True,
    default=False,
    help="Show dates from all versions.",
)
@click.option(
    "-o",
    "--output-format",
    type=click.Choice([of for of in OutputFormat]),
    default=OutputFormat.table,
    help="Output format.",
)
@click.pass_obj
@validate_call
def config_dates_show(ctx: Project, version: ProjectVersion | None, all: bool, output_format: OutputFormat) -> None:
    """Show dates from the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to show dates from. If None, the last version is used.
        all: Flag to show dates from all versions of the configuration.
        output_format: The output format for displaying the dates.
    """
    show_dates_config(config=ctx.config, output_format=output_format, all=all, version=version)

config_edit(ctx)

Launch editor with project's configuration file.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required

Source code in sereto/cli/cli.py

@config.command(name="edit")
@handle_exceptions
@click.pass_obj
def config_edit(ctx: Project) -> None:
    """Launch editor with project's configuration file.\f

    Args:
        ctx: Project's representation.
    """
    edit_config(project=ctx)

config_people()

Configuration of people.

This group of commands allows you to manage the people configuration of a project.

Source code in sereto/cli/cli.py

@config.group(cls=AliasedGroup, name="people")
def config_people() -> None:
    """Configuration of people.

    This group of commands allows you to manage the people configuration of a project.
    """
    pass

config_people_add(ctx, version)

Add person to the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to add the person to. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_people.command(name="add")
@handle_exceptions
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_people_add(ctx: Project, version: ProjectVersion | None) -> None:
    """Add person to the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to add the person to. If None, the last version is used.
    """
    add_people_config(config=ctx.config, version=version)

config_people_delete(ctx, index, version)

Delete person from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
index	int	The index of the person to be deleted. You can obtain the index by running sereto config people show.	required
version	ProjectVersion | None	The specific version of the configuration to delete the person from. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_people.command(name="delete")
@handle_exceptions
@click.option("-i", "--index", required=True, type=int, help="Person index to be deleted.")
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_people_delete(ctx: Project, index: int, version: ProjectVersion | None) -> None:
    """Delete person from the project's configuration.\f

    Args:
        ctx: Project's representation.
        index: The index of the person to be deleted. You can obtain the index by running `sereto config people show`.
        version: The specific version of the configuration to delete the person from. If None, the last version is
            used.
    """
    if version is None:
        version = ctx.config.last_version

    # Delete the date from the configuration
    ctx.config.at_version(version).delete_person(index=index)

    # Write the configuration
    ctx.config.save()

config_people_show(ctx, version, all, output_format)

Show people from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to show people from. If None, the last version is used.	required
all	bool	Flag to show people from all versions of the configuration.	required
output_format	OutputFormat	The output format for displaying the people.	required

Source code in sereto/cli/cli.py

@config_people.command(name="show")
@handle_exceptions
@click.option("-v", "--version", help="Show people at specific version, e.g. 'v1.0'.")
@click.option(
    "-a",
    "--all",
    is_flag=True,
    show_default=True,
    default=False,
    help="Show people from all versions.",
)
@click.option(
    "-o",
    "--output-format",
    type=click.Choice([of for of in OutputFormat]),
    default=OutputFormat.table,
    help="Output format.",
)
@click.pass_obj
@validate_call
def config_people_show(ctx: Project, version: ProjectVersion | None, all: bool, output_format: OutputFormat) -> None:
    """Show people from the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to show people from. If None, the last version is used.
        all: Flag to show people from all versions of the configuration.
        output_format: The output format for displaying the people.
    """
    show_people_config(config=ctx.config, output_format=output_format, all=all, version=version)

config_show(ctx, version, all, output_format)

Show the projects's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to show. If None, the last version is used.	required
all	bool	Flag to show all versions of the configuration.	required
output_format	OutputFormat	The output format for displaying the configuration.	required

Source code in sereto/cli/cli.py

@config.command(name="show")
@handle_exceptions
@click.option("-v", "--version", help="Show config at specific version, e.g. 'v1.0'.")
@click.option(
    "-a",
    "--all",
    is_flag=True,
    show_default=True,
    default=False,
    help="Show all versions.",
)
@click.option(
    "-o",
    "--output-format",
    type=click.Choice([of for of in OutputFormat]),
    default=OutputFormat.table,
    help="Output format.",
)
@click.pass_obj
@validate_call
def config_show(ctx: Project, version: ProjectVersion | None, all: bool, output_format: OutputFormat) -> None:
    """Show the projects's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to show. If None, the last version is used.
        all: Flag to show all versions of the configuration.
        output_format: The output format for displaying the configuration.
    """
    show_config(config=ctx.config, output_format=output_format, all=all, version=version)

config_targets()

Configuration of targets.

This group of commands allows you to manage the targets configuration of a project.

Source code in sereto/cli/cli.py

@config.group(cls=AliasedGroup, name="targets")
def config_targets() -> None:
    """Configuration of targets.

    This group of commands allows you to manage the targets configuration of a project.
    """

config_targets_add(ctx, version)

Add targets to the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to add the targets to. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_targets.command(name="add")
@handle_exceptions
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_targets_add(ctx: Project, version: ProjectVersion | None) -> None:
    """Add targets to the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to add the targets to. If None, the last version is used.
    """
    add_target(
        project_path=ctx.path,
        templates=ctx.settings.templates_path,
        config=ctx.config,
        categories=ctx.settings.categories,
        version=version,
    )

config_targets_delete(ctx, index, version)

Delete target from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
index	int	The index of the target to be deleted. You can obtain the index by running sereto config targets show.	required
version	ProjectVersion | None	The specific version of the configuration to delete the target from. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@config_targets.command(name="delete")
@handle_exceptions
@click.option("-i", "--index", required=True, type=int, help="Target index to be deleted.")
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def config_targets_delete(ctx: Project, index: int, version: ProjectVersion | None) -> None:
    """Delete target from the project's configuration.\f

    Args:
        ctx: Project's representation.
        index: The index of the target to be deleted. You can obtain the index by running `sereto config targets show`.
        version: The specific version of the configuration to delete the target from. If None, the last version is
            used.
    """
    delete_target(config=ctx.config, index=index, version=version, interactive=True)

config_targets_show(ctx, version, all, output_format)

Show targets from the project's configuration.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The specific version of the configuration to show targets from. If None, the last version is used.	required
all	bool	Flag to show targets from all versions of the configuration.	required
output_format	OutputFormat	The output format for displaying the targets.	required

Source code in sereto/cli/cli.py

@config_targets.command(name="show")
@handle_exceptions
@click.option("-v", "--version", help="Show targets at specific version, e.g. 'v1.0'.")
@click.option(
    "-a",
    "--all",
    is_flag=True,
    show_default=True,
    default=False,
    help="Show targets from all versions.",
)
@click.option(
    "-o",
    "--output-format",
    type=click.Choice([of for of in OutputFormat]),
    default=OutputFormat.table,
    help="Output format.",
)
@click.pass_obj
@validate_call
def config_targets_show(ctx: Project, version: ProjectVersion | None, all: bool, output_format: OutputFormat) -> None:
    """Show targets from the project's configuration.\f

    Args:
        ctx: Project's representation.
        version: The specific version of the configuration to show targets from. If None, the last version is used.
        all: Flag to show targets from all versions of the configuration.
        output_format: The output format for displaying the targets.
    """
    show_targets_config(config=ctx.config, output_format=output_format, all=all, version=version)

decrypt(ctx, file)

Extract the SeReTo project from the encrypted archive.

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.option("-f", "--file", required=True, help="Path to the source.sereto file.", type=Path)
@click.pass_obj
@validate_call
def decrypt(ctx: Project, file: FilePath) -> None:
    """Extract the SeReTo project from the encrypted archive."""
    source_tgz = decrypt_file(file=file, keep_original=True)
    extract_source_archive(file=source_tgz, output_dir=ctx.settings.projects_path, keep_original=False)

finding_add(ctx)

Launch TUI app for searching and adding findings from templates.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required

Source code in sereto/cli/cli.py

@findings.command(name="add")
@handle_exceptions
@click.pass_obj
@validate_call
def finding_add(ctx: Project) -> None:
    """Launch TUI app for searching and adding findings from templates.\f

    Args:
        ctx: Project's representation.
    """
    asyncio.run(launch_finding_tui())

finding_show(ctx, version)

Show findings.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The version of the findings to show. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@findings.command(name="show")
@handle_exceptions
# @click.option("--target", "-t", type=str, help="Specify target (required for more than one).")
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def finding_show(ctx: Project, version: ProjectVersion | None) -> None:
    """Show findings.\f

    Args:
        ctx: Project's representation.
        version: The version of the findings to show. If None, the last version is used.
    """
    if version is None:
        version = ctx.config.last_version
    show_findings(version_config=ctx.config.at_version(version))

findings()

Operations with findings.

This group of commands allows you to manage the findings of a project.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def findings() -> None:
    """Operations with findings.

    This group of commands allows you to manage the findings of a project.
    """

is_in_repl_shell()

Return True when the command execution is inside the REPL session.

Source code in sereto/cli/cli.py

def is_in_repl_shell() -> bool:
    """Return True when the command execution is inside the REPL session."""
    ctx = click.get_current_context(silent=True)
    if ctx is None:
        return False
    return ctx.meta.get("in_repl", False)

load_plugins()

Load plugins from the plugins directory.

This function loads plugins from the configured directory and registers their commands with the CLI. The plugin support needs to be enabled in the settings.

Source code in sereto/cli/cli.py

def load_plugins() -> None:
    """Load plugins from the plugins directory.

    This function loads plugins from the configured directory and registers their commands with the CLI. The plugin
    support needs to be enabled in the settings.
    """
    settings = load_settings_function()

    # Check if plugins are enabled
    if not settings.plugins.enabled:
        return
    # Get plugins directory
    plugins_dir = Path(
        replace_strings(text=settings.plugins.directory, replacements={"%TEMPLATES%": str(settings.templates_path)})
    )
    if not plugins_dir.is_dir():
        raise SeretoPathError(f"Plugins directory not found: '{plugins_dir}'")

    # Ensure plugins directory is in a package-importable location
    plugins_parent = plugins_dir.parent
    if not plugins_parent.is_dir():
        raise SeretoPathError(f"Plugins parent directory not found: '{plugins_parent}'")
    if not (plugins_dir / "__init__.py").exists():
        raise SeretoPathError(f"Plugins directory '{plugins_dir}' is not a package (missing __init__.py)")
    if str(plugins_parent) not in sys.path:
        sys.path.insert(0, str(plugins_parent))
    # Compatibility for older SeReTo plugins; add plugins directory at the end of sys.path
    if str(plugins_dir) not in sys.path:
        sys.path.append(str(plugins_dir))

    # Load plugins from the directory
    for file in plugins_dir.iterdir():
        # Skip dunder files like __init__.py
        if file.name.startswith("__"):
            continue

        if file.is_dir() and (file / "__init__.py").exists():
            # It's a package
            module_name = f"plugins.{file.name}"
            module_path = file / "__init__.py"
            submodule_search_locations = [str(file)]
        elif file.suffix == ".py":
            module_name = f"plugins.{file.name[:-3]}"
            module_path = file
            submodule_search_locations = None
        else:
            continue

        # Register commands
        try:
            # Create a module specification
            spec = importlib.util.spec_from_file_location(
                module_name, module_path, submodule_search_locations=submodule_search_locations
            )
            if spec is None or spec.loader is None:
                logger.error("Failed to load plugin: {}", file.name)
                continue

            # Create a new module based on the specification
            module = importlib.util.module_from_spec(spec)

            # Execute the module to initialize it
            spec.loader.exec_module(module)
        except ModuleNotFoundError as e:
            logger.error("Module '{}' referenced in plugin '{}' not found.", e.name, file.name)
            continue

        # Run the plugin's register_commands function
        if hasattr(module, "register_commands"):
            module.register_commands(cli)
            logger.debug("Plugin registered: '{}'", file.name)

ls(ctx)

List all available projects.

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.pass_obj
def ls(ctx: Project) -> None:
    """List all available projects."""
    sereto_ls(settings=ctx.settings)

new(ctx, project_id)

Create a new project.

 Example:

sereto new PT01234



Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
project_id	TypeProjectId	The ID of the project to be created.	required

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.argument("project_id")
@click.pass_obj
@validate_call
def new(ctx: Project, project_id: TypeProjectId) -> None:
    """Create a new project.

    \b
    Example:
        ```sh
        sereto new PT01234
        ```
    \f

    Args:
        ctx: Project's representation.
        project_id: The ID of the project to be created.
    """
    Console().print("[cyan]We will ask you a few questions to set up the new project.\n")
    name = prompt("Name of the project: ")
    new_project(
        projects_path=ctx.settings.projects_path,
        templates_path=ctx.settings.templates_path,
        risk_due_dates=ctx.settings.risk_due_dates,
        id=project_id,
        name=name,
        people=ctx.settings.default_people,
    )

    # Only change the working directory when this command runs from inside REPL.
    if is_in_repl_shell():
        repl_cd_impl(project_id=project_id)

open()

Open report, Statement of Work (SoW), or the project's folder.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def open() -> None:
    """Open report, Statement of Work (SoW), or the project's folder."""

open_folder(ctx)

Open the folder containing the current project.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required

Source code in sereto/cli/cli.py

@open.command(name="folder")
@handle_exceptions
@click.pass_obj
def open_folder(ctx: Project) -> None:
    """Open the folder containing the current project.\f

    Args:
        ctx: Project's representation.
    """
    click.launch(str(ctx.path))

open_report(ctx, version)

Open the report document in the default PDF viewer.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The version of the report that is opened. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@open.command(name="report")
@handle_exceptions
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def open_report(ctx: Project, version: ProjectVersion | None) -> None:
    """Open the report document in the default PDF viewer.\f

    Args:
        ctx: Project's representation.
        version: The version of the report that is opened. If None, the last version is used.
    """
    version_config = ctx.config.at_version(version) if version else ctx.config.last_config

    if not (report_path := ctx.path / "pdf" / version_config.report_name).is_file():
        raise SeretoPathError(f"File not found '{report_path}'")

    click.launch(str(report_path))

open_sow(ctx, version)

Open the Statement of Work (SoW) document in the default PDF viewer.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
version	ProjectVersion | None	The version of the SoW that is opened. If None, the last version is used.	required

Source code in sereto/cli/cli.py

@open.command(name="sow")
@handle_exceptions
@click.option("-v", "--version", help="Use specific version, e.g. 'v1.0'.")
@click.pass_obj
@validate_call
def open_sow(ctx: Project, version: ProjectVersion | None) -> None:
    """Open the Statement of Work (SoW) document in the default PDF viewer.\f

    Args:
        ctx: Project's representation.
        version: The version of the SoW that is opened. If None, the last version is used.
    """
    version_config = ctx.config.at_version(version) if version else ctx.config.last_config

    if not (sow_path := ctx.path / "pdf" / version_config.sow_name).is_file():
        raise SeretoPathError(f"File not found '{sow_path}'")

    click.launch(str(sow_path))

oxipng(ctx)

Lossless PNGs compression.

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.pass_obj
@validate_call
def oxipng(ctx: Project) -> None:
    """Lossless PNGs compression."""
    run_oxipng(project_path=ctx.path)

password()

Manage password for the encryption of attached archives.

Source code in sereto/cli/cli.py

@settings.group(cls=AliasedGroup)
def password() -> None:
    """Manage password for the encryption of attached archives."""

pdf()

Render PDF documents.

This group of commands allows you to render a PDF report or Statement of Work.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def pdf() -> None:
    """Render PDF documents.

    This group of commands allows you to render a PDF report or Statement of Work.
    """

repl()

Start an interactive shell (REPL) for SeReTo.

Source code in sereto/cli/cli.py

@cli.command()
def repl() -> None:
    """Start an interactive shell (REPL) for SeReTo."""
    sereto_repl(cli=cli)

retest(ctx)

Add retest to the project.

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required

Source code in sereto/cli/cli.py

@cli.command(name="retest")
@handle_exceptions
@click.pass_obj
def retest(ctx: Project) -> None:
    """Add retest to the project.\f

    Args:
        ctx: Project's representation.
    """
    add_retest(project=ctx)

settings()

Manage global settings.

This group of commands allows you to display and edit the global settings.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def settings() -> None:
    """Manage global settings.

    This group of commands allows you to display and edit the global settings.
    """

settings_edit()

Edit settings with the configured editor.

This command opens the global settings configuration file in the default editor. If the configuration file does not exist, it will be created first with the default values.

Source code in sereto/cli/cli.py

@settings.command(name="edit")
@handle_exceptions
def settings_edit() -> None:
    """Edit settings with the configured editor.

    This command opens the global settings configuration file in the default editor.
    If the configuration file does not exist, it will be created first with the default values.
    """
    if not (path := Settings.get_path()).is_file():
        load_settings_function()
    click.edit(filename=str(path))

settings_password_get()

Get the password for the encryption of attached archives.

This will print the password from the system's keyring.

Source code in sereto/cli/cli.py

@password.command(name="get")
@handle_exceptions
def settings_password_get() -> None:
    """Get the password for the encryption of attached archives.

    This will print the password from the system's keyring.
    """
    click.echo(get_password("sereto", "encrypt_attached_archive"))

settings_password_set(password)

Set the password for the encryption of attached archives.

This will store the password in the system's keyring. 

Parameters:

Name	Type	Description	Default
password	str	The password to be stored.	required

Source code in sereto/cli/cli.py

@password.command(name="set")
@handle_exceptions
@validate_call
@click.option("--password", prompt=True, hide_input=True)
def settings_password_set(password: str) -> None:
    """Set the password for the encryption of attached archives.

    This will store the password in the system's keyring.
    \f

    Args:
        password: The password to be stored.
    """
    set_password("sereto", "encrypt_attached_archive", password)

settings_show(ctx)

Display the current settings.

This function prints the current settings of the tool, including both the set values and the default values for any unset settings. 

Parameters:

Name	Type	Description	Default
ctx	Project	The settings object containing the tool's global configuration.	required

Source code in sereto/cli/cli.py

@settings.command(name="show")
@handle_exceptions
@click.pass_obj
def settings_show(ctx: Project) -> None:
    """Display the current settings.

    This function prints the current settings of the tool, including both the set values and the default values for any
    unset settings.
    \f

    Args:
        ctx: The settings object containing the tool's global configuration.
    """
    Console().print_json(ctx.settings.model_dump_json())

skel()

Project template skeleton files.

Source code in sereto/cli/cli.py

@templates.group(cls=AliasedGroup)
def skel() -> None:
    """Project template skeleton files."""

target_skel()

Target template skeleton files.

Source code in sereto/cli/cli.py

@templates.group(cls=AliasedGroup)
def target_skel() -> None:
    """Target template skeleton files."""

templates()

Operations with templates.

This group of commands allows you to copy project's skeleton from templates.

Source code in sereto/cli/cli.py

@cli.group(cls=AliasedGroup)
def templates() -> None:
    """Operations with templates.

    This group of commands allows you to copy project's skeleton from templates.
    """

templates_skel_copy(ctx)

Update the project's templates from the skeleton directory.

This function copies all files from the templates skeleton directory to the project's directory, overwriting any existing files. 

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required

Source code in sereto/cli/cli.py

@skel.command(name="copy")
@handle_exceptions
@click.pass_obj
def templates_skel_copy(ctx: Project) -> None:
    """Update the project's templates from the skeleton directory.

    This function copies all files from the templates skeleton directory to the project's directory, overwriting any
    existing files.
    \f

    Args:
        ctx: Project's representation.
    """
    copy_skel(templates=ctx.settings.templates_path, dst=ctx.path, overwrite=True)

templates_target_skel_copy(ctx, target)

Update the target's templates from the skeleton directory.

This function copies all files from the templates skeleton directory to the target's directory, overwriting any existing files. 

Parameters:

Name	Type	Description	Default
ctx	Project	Project's representation.	required
target	str | None	Selector of a target for which the templates are being copied.	required

Source code in sereto/cli/cli.py

@target_skel.command(name="copy")
@handle_exceptions
@click.option("--target", "-t", type=str, help="Specify target (required for more than one).")
@click.pass_obj
@validate_call
def templates_target_skel_copy(ctx: Project, target: str | None) -> None:
    """Update the target's templates from the skeleton directory.

    This function copies all files from the templates skeleton directory to the target's directory, overwriting any
    existing files.
    \f

    Args:
        ctx: Project's representation.
        target: Selector of a target for which the templates are being copied.
    """
    selected_target = ctx.config.last_config.select_target(categories=ctx.settings.categories, selector=target)

    copy_skel(
        templates=ctx.settings.templates_path / "categories" / selected_target.data.category,
        dst=selected_target.path,
        overwrite=True,
    )

unpack(ctx, file)

Unpack the SeReTo project from the report's PDF.

Source code in sereto/cli/cli.py

@cli.command()
@handle_exceptions
@click.option("-f", "--file", required=True, help="Path to the PDF file.", type=Path)
@click.pass_obj
@validate_call
def unpack(ctx: Project, file: FilePath) -> None:
    """Unpack the SeReTo project from the report's PDF."""
    attachment: Path | None = None

    with suppress(SeretoValueError):
        attachment = retrieve_source_archive(pdf=file, name="source.sereto")

    if attachment is not None:
        source_tgz = decrypt_file(file=attachment, keep_original=False)
    else:
        source_tgz = retrieve_source_archive(pdf=file, name="source.tgz")

    extract_source_archive(file=source_tgz, output_dir=ctx.settings.projects_path, keep_original=False)