Skip to content
v0.1.3

History Module API Reference

This section documents the internals of the history module in Bijux CLI.

bijux_cli.contracts.history

Defines the contract for the command history management service.

This module specifies the HistoryProtocol, a formal interface that any service responsible for recording, retrieving, and managing CLI command history events must implement.

HistoryProtocol

Bases: Protocol

Defines the contract for command history management.

This interface specifies the methods for recording, retrieving, and managing command history events, including persistence and import/export functionality.

add 

add(
    command: str,
    *,
    params: Sequence[str] | None = None,
    success: bool | None = True,
    return_code: int | None = 0,
    duration_ms: float | None = None,
) -> None

Records a command execution event.

Parameters:

  • command (str) –

    The full command string (e.g., "status --verbose").

  • params (Sequence[str] | None, default: None ) –

    The raw argument vector as executed.

  • success (bool | None, default: True ) –

    True if the command was successful.

  • return_code (int | None, default: 0 ) –

    The integer exit code of the command.

  • duration_ms (float | None, default: None ) –

    Total execution time in milliseconds.

Returns:

  • None ( None ) –
Source code in src/bijux_cli/contracts/history.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def add(
    self,
    command: str,
    *,
    params: Sequence[str] | None = None,
    success: bool | None = True,
    return_code: int | None = 0,
    duration_ms: float | None = None,
) -> None:
    """Records a command execution event.

    Args:
        command (str): The full command string (e.g., "status --verbose").
        params (Sequence[str] | None): The raw argument vector as executed.
        success (bool | None): True if the command was successful.
        return_code (int | None): The integer exit code of the command.
        duration_ms (float | None): Total execution time in milliseconds.

    Returns:
        None:
    """
    ...

clear 

clear() -> None

Erases all command history events from the store.

Source code in src/bijux_cli/contracts/history.py 
73
74
75
def clear(self) -> None:
    """Erases all command history events from the store."""
    ...

export 

export(path: Path) -> None

Exports all history entries to a file.

Parameters:

  • path (Path) –

    The target file path, which will be overwritten.

Returns:

  • None ( None ) –
Source code in src/bijux_cli/contracts/history.py 
81
82
83
84
85
86
87
88
89
90
def export(self, path: Path) -> None:
    """Exports all history entries to a file.

    Args:
        path (Path): The target file path, which will be overwritten.

    Returns:
        None:
    """
    ...

flush 

flush() -> None

Persists any in-memory history data to permanent storage.

Source code in src/bijux_cli/contracts/history.py 
77
78
79
def flush(self) -> None:
    """Persists any in-memory history data to permanent storage."""
    ...

import_ 

import_(path: Path) -> None

Imports history entries from a file, replacing existing entries.

Parameters:

  • path (Path) –

    The source file path containing history data.

Returns:

  • None ( None ) –
Source code in src/bijux_cli/contracts/history.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def import_(self, path: Path) -> None:
    """Imports history entries from a file, replacing existing entries.

    Args:
        path (Path): The source file path containing history data.

    Returns:
        None:
    """
    ...

list 

list(
    *,
    limit: int | None = 20,
    group_by: str | None = None,
    filter_cmd: str | None = None,
    sort: str | None = None,
) -> list[dict[str, Any]]

Retrieves command history events.

Parameters:

  • limit (int | None, default: 20 ) –

    The maximum number of events to return.

  • group_by (str | None, default: None ) –

    A field name to group events by.

  • filter_cmd (str | None, default: None ) –

    A substring to filter commands by.

  • sort (str | None, default: None ) –

    A field name to sort the results by.

Returns:

  • list[dict[str, Any]] –

    list[dict[str, Any]]: A list of history event dictionaries.

Source code in src/bijux_cli/contracts/history.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def list(
    self,
    *,
    limit: int | None = 20,
    group_by: str | None = None,
    filter_cmd: str | None = None,
    sort: str | None = None,
) -> list[dict[str, Any]]:
    """Retrieves command history events.

    Args:
        limit (int | None): The maximum number of events to return.
        group_by (str | None): A field name to group events by.
        filter_cmd (str | None): A substring to filter commands by.
        sort (str | None): A field name to sort the results by.

    Returns:
        list[dict[str, Any]]: A list of history event dictionaries.
    """
    ...