Clear Command API Reference¶

This section documents the internals of the clear command in Bijux CLI.

bijux_cli.commands.history.clear ¶

Implements the history clear subcommand for the Bijux CLI.

This module contains the logic for permanently erasing all entries from the command history store. This action is irreversible. A structured confirmation is emitted upon success.

Output Contract

Success: {"status": "cleared"}
Verbose: Adds {"python": str, "platform": str} to the payload.
Error: {"error": str, "code": int}

Exit Codes

0: Success.
1: An unexpected error occurred, such as the history service being unavailable or a failure during the clear operation.

clear_history ¶

clear_history(
    quiet: bool = Option(
        False, "-q", "--quiet", help=HELP_QUIET
    ),
    verbose: bool = Option(
        False, "-v", "--verbose", help=HELP_VERBOSE
    ),
    fmt: str = Option(
        "json", "-f", "--format", help=HELP_FORMAT
    ),
    pretty: bool = Option(
        True, "--pretty/--no-pretty", help=HELP_NO_PRETTY
    ),
    debug: bool = Option(
        False, "-d", "--debug", help=HELP_DEBUG
    ),
) -> None

Erases all stored command history.

This command permanently removes all entries from the history store and emits a structured payload to confirm the operation.

Parameters:

quiet (bool, default: Option(False, '-q', '--quiet', help=HELP_QUIET) ) –

If True, suppresses all output except for errors.
verbose (bool, default: Option(False, '-v', '--verbose', help=HELP_VERBOSE) ) –

If True, includes Python/platform details in the output.
fmt (str, default: Option('json', '-f', '--format', help=HELP_FORMAT) ) –

The output format, "json" or "yaml".
pretty (bool, default: Option(True, '--pretty/--no-pretty', help=HELP_NO_PRETTY) ) –

If True, pretty-prints the output.
debug (bool, default: Option(False, '-d', '--debug', help=HELP_DEBUG) ) –

If True, enables debug diagnostics.

Returns:

None ( None ) –

Raises:

SystemExit –

Always exits with a contract-compliant status code and payload, indicating success or detailing an error.

Source code in src/bijux_cli/commands/history/clear.py

def clear_history(
    quiet: bool = typer.Option(False, "-q", "--quiet", help=HELP_QUIET),
    verbose: bool = typer.Option(False, "-v", "--verbose", help=HELP_VERBOSE),
    fmt: str = typer.Option("json", "-f", "--format", help=HELP_FORMAT),
    pretty: bool = typer.Option(True, "--pretty/--no-pretty", help=HELP_NO_PRETTY),
    debug: bool = typer.Option(False, "-d", "--debug", help=HELP_DEBUG),
) -> None:
    """Erases all stored command history.

    This command permanently removes all entries from the history store and
    emits a structured payload to confirm the operation.

    Args:
        quiet (bool): If True, suppresses all output except for errors.
        verbose (bool): If True, includes Python/platform details in the output.
        fmt (str): The output format, "json" or "yaml".
        pretty (bool): If True, pretty-prints the output.
        debug (bool): If True, enables debug diagnostics.

    Returns:
        None:

    Raises:
        SystemExit: Always exits with a contract-compliant status code and
            payload, indicating success or detailing an error.
    """
    command = "history clear"
    if debug:
        verbose = True
        pretty = True
    include_runtime = verbose

    fmt_lower = validate_common_flags(
        fmt,
        command,
        quiet,
        include_runtime=include_runtime,
    )

    history_svc = resolve_history_service(
        command, fmt_lower, quiet, include_runtime, debug
    )

    try:
        history_svc.clear()
    except Exception as exc:
        emit_error_and_exit(
            f"Failed to clear history: {exc}",
            code=1,
            failure="clear_failed",
            command=command,
            fmt=fmt_lower,
            quiet=quiet,
            include_runtime=include_runtime,
            debug=debug,
        )

    def payload_builder(include_runtime: bool) -> Mapping[str, Any]:
        """Builds the payload confirming the history was cleared.

        Args:
            include_runtime (bool): If True, includes Python and platform info.

        Returns:
            Mapping[str, Any]: The structured payload.
        """
        payload: dict[str, Any] = {"status": "cleared"}
        if include_runtime:
            payload["python"] = ascii_safe(platform.python_version(), "python_version")
            payload["platform"] = ascii_safe(platform.platform(), "platform")
        return payload

    new_run_command(
        command_name=command,
        payload_builder=payload_builder,
        quiet=quiet,
        verbose=verbose,
        fmt=fmt_lower,
        pretty=pretty,
        debug=debug,
    )

resolve_history_service ¶

resolve_history_service(
    command: str,
    fmt_lower: str,
    quiet: bool,
    include_runtime: bool,
    debug: bool,
) -> HistoryProtocol

Resolves the HistoryProtocol implementation from the DI container.

Parameters:

command (str) –

The full command name (e.g., "history clear").
fmt_lower (str) –

The chosen output format, lowercased.
quiet (bool) –

If True, suppresses non-error output.
include_runtime (bool) –

If True, includes runtime metadata in errors.
debug (bool) –

If True, enables debug diagnostics.

Returns:

HistoryProtocol ( HistoryProtocol ) –

An instance of the history service.

Raises:

SystemExit –

Exits with a structured error if the service cannot be resolved from the container.

Source code in src/bijux_cli/commands/history/clear.py

def resolve_history_service(
    command: str, fmt_lower: str, quiet: bool, include_runtime: bool, debug: bool
) -> HistoryProtocol:
    """Resolves the HistoryProtocol implementation from the DI container.

    Args:
        command (str): The full command name (e.g., "history clear").
        fmt_lower (str): The chosen output format, lowercased.
        quiet (bool): If True, suppresses non-error output.
        include_runtime (bool): If True, includes runtime metadata in errors.
        debug (bool): If True, enables debug diagnostics.

    Returns:
        HistoryProtocol: An instance of the history service.

    Raises:
        SystemExit: Exits with a structured error if the service cannot be
            resolved from the container.
    """
    try:
        return DIContainer.current().resolve(HistoryProtocol)
    except Exception as exc:
        emit_error_and_exit(
            f"History service unavailable: {exc}",
            code=1,
            failure="service_unavailable",
            command=command,
            fmt=fmt_lower,
            quiet=quiet,
            include_runtime=include_runtime,
            debug=debug,
        )