Status Command API Reference¶

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

bijux_cli.commands.status ¶

Implements the status command for the Bijux CLI.

This module provides a lightweight "liveness probe" for the CLI, designed for health checks and monitoring. In its default mode, it performs a quick check and returns a simple "ok" status. It also supports a continuous "watch" mode that emits status updates at a regular interval.

Output Contract

Success: {"status": "ok"}
Verbose: Adds {"python": str, "platform": str} to the payload.
Watch Mode Tick: {"status": "ok", "ts": float, ...}
Watch Mode Stop: {"status": "watch-stopped", ...}
Error: {"error": str, "code": int}

Exit Codes

0: Success.
1: Internal or fatal error during execution.
2: Invalid argument (e.g., bad watch interval or format).
3: ASCII encoding error.

status ¶

status(
    ctx: Context,
    watch: float | None = Option(
        None, "--watch", help="Poll every N seconds"
    ),
    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

Defines the entrypoint and logic for the bijux status command.

This function orchestrates the status check. It validates flags and then dispatches to either the single-run logic or the continuous watch mode based on the presence of the --watch flag.

Parameters:

ctx (Context) –

The Typer context for the CLI.
watch (float | None, default: Option(None, '--watch', help='Poll every N seconds') ) –

If provided, enters watch mode, polling at this interval in seconds. Must be a positive number.
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 and platform details in the output payload.
fmt (str, default: Option('json', '-f', '--format', help=HELP_FORMAT) ) –

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

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

If True, enables debug diagnostics, implying verbose and pretty.

Returns:

None ( None ) –

Raises:

SystemExit –

Exits with a contract-compliant status code and payload upon any error, such as an invalid watch interval.

Source code in src/bijux_cli/commands/status.py

@status_app.callback(invoke_without_command=True)
def status(
    ctx: typer.Context,
    watch: float | None = typer.Option(None, "--watch", help="Poll every N seconds"),
    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:
    """Defines the entrypoint and logic for the `bijux status` command.

    This function orchestrates the status check. It validates flags and then
    dispatches to either the single-run logic or the continuous watch mode
    based on the presence of the `--watch` flag.

    Args:
        ctx (typer.Context): The Typer context for the CLI.
        watch (float | None): If provided, enters watch mode, polling at this
            interval in seconds. Must be a positive number.
        quiet (bool): If True, suppresses all output except for errors.
        verbose (bool): If True, includes Python and platform details in the
            output payload.
        fmt (str): The output format, either "json" or "yaml". Watch mode only
            supports "json".
        pretty (bool): If True, pretty-prints the output for human readability.
        debug (bool): If True, enables debug diagnostics, implying `verbose`
            and `pretty`.

    Returns:
        None:

    Raises:
        SystemExit: Exits with a contract-compliant status code and payload
            upon any error, such as an invalid watch interval.
    """
    if ctx.invoked_subcommand:
        return

    emitter = DIContainer.current().resolve(EmitterProtocol)
    telemetry = DIContainer.current().resolve(TelemetryProtocol)
    command = "status"

    fmt_lower = validate_common_flags(fmt, command, quiet)

    if watch is not None:
        try:
            interval = float(watch)
            if interval <= 0:
                raise ValueError
        except (ValueError, TypeError):
            emit_error_and_exit(
                "Invalid watch interval: must be > 0",
                code=2,
                failure="interval",
                command=command,
                fmt=fmt_lower,
                quiet=quiet,
                include_runtime=verbose,
                debug=debug,
            )

        _run_watch_mode(
            command=command,
            watch_interval=interval,
            fmt=fmt_lower,
            quiet=quiet,
            verbose=verbose,
            debug=debug,
            effective_pretty=pretty,
            include_runtime=verbose,
            telemetry=telemetry,
            emitter=emitter,
        )
    else:
        new_run_command(
            command_name=command,
            payload_builder=lambda include: _build_payload(include),
            quiet=quiet,
            verbose=verbose,
            fmt=fmt_lower,
            pretty=pretty,
            debug=debug,
        )