CLI App

Main CLI application entry point.

This module defines the qsh command-line application, its top-level callback, and a set of built-in commands. Plugins are discovered and loaded lazily to keep startup fast.

Examples: Running the CLI and showing help::

    qsh --help

Starting the REPL with a specific context and JSON output::

    qsh --context prod --output json repl

Listing tasks with the context's ``m2m`` auth provider instead of its default::

    qsh --auth m2m tasks list

Printing shell completion for zsh::

    qsh completion zsh > ~/.zsh/completions/_qsh

OutputFormat

Bases: str, Enum


              flowchart TD
              qsh.cli.app.OutputFormat[OutputFormat]

              

              click qsh.cli.app.OutputFormat href "" "qsh.cli.app.OutputFormat"

Output format options for the CLI.

app_callback

app_callback(context: Annotated[str | None, Option('--context', help='Select context from config')] = None, auth: Annotated[str | None, Option('--auth', metavar='PROVIDER', help='Auth provider from the current context for API commands and auth whoami (overrides the plugin and default auth_provider)')] = None, output: Annotated[OutputFormat | None, Option('-o', '--output', help='Output format: table|json')] = None, verbose: Annotated[bool, Option('--verbose', '-v', help='Enable verbose logging')] = False, wrap: Annotated[bool, Option('--wrap', help='Allow multiline wrapping in table output')] = False, private: Annotated[bool, Option('--private', help='Use private API endpoints (requires super admin access)')] = False) -> None

CLI for QuEra's Quantum Computing Service.

Parameters:

Name	Type	Description	Default
`context`	`Annotated[str \| None, Option('--context', help='Select context from config')]`	Optional config context to use for this invocation.	`None`
`auth`	`Annotated[str \| None, Option('--auth', metavar='PROVIDER', help='Auth provider from the current context for API commands and auth whoami (overrides the plugin and default auth_provider)')]`	Optional `auth_providers` entry name in the current context to authenticate with for this invocation, instead of the configured default.	`None`
`output`	`Annotated[OutputFormat \| None, Option('-o', '--output', help='Output format: table\|json')]`	Optional output format override ("table" or "json").	`None`
`verbose`	`Annotated[bool, Option('--verbose', '-v', help='Enable verbose logging')]`	Enable verbose logging for diagnostics.	`False`
`wrap`	`Annotated[bool, Option('--wrap', help='Allow multiline wrapping in table output')]`	Allow multiline wrapping in table output.	`False`
`private`	`Annotated[bool, Option('--private', help='Use private API endpoints (requires super admin access)')]`	Use private API endpoints (requires super admin access).	`False`

Source code in qsh/cli/app.py

@app.callback()
def app_callback(
    context: Annotated[
        str | None, typer.Option("--context", help="Select context from config")
    ] = None,
    auth: Annotated[
        str | None,
        typer.Option(
            "--auth",
            metavar="PROVIDER",
            help=(
                "Auth provider from the current context for API commands and auth whoami "
                "(overrides the plugin and default auth_provider)"
            ),
        ),
    ] = None,
    output: Annotated[
        OutputFormat | None,
        typer.Option("-o", "--output", help="Output format: table|json"),
    ] = None,
    verbose: Annotated[
        bool, typer.Option("--verbose", "-v", help="Enable verbose logging")
    ] = False,
    wrap: Annotated[
        bool, typer.Option("--wrap", help="Allow multiline wrapping in table output")
    ] = False,
    private: Annotated[
        bool,
        typer.Option("--private", help="Use private API endpoints (requires super admin access)"),
    ] = False,
) -> None:
    """CLI for QuEra's Quantum Computing Service.

    :param context: Optional config context to use for this invocation.
    :param auth: Optional ``auth_providers`` entry name in the current context to
        authenticate with for this invocation, instead of the configured default.
    :param output: Optional output format override ("table" or "json").
    :param verbose: Enable verbose logging for diagnostics.
    :param wrap: Allow multiline wrapping in table output.
    :param private: Use private API endpoints (requires super admin access).
    """

    logger = setup_logging(verbose)
    logger.debug("CLI started with verbose logging enabled" if verbose else "CLI started")

    app.state = {
        "context": context,
        "auth": auth,
        "output": output,
        "verbose": verbose,
        "wrap": wrap,
        "private": private,
    }

clear_app_context_cache

clear_app_context_cache() -> None

Clear the cached AppContext and config to force reload next time.

Source code in qsh/cli/app.py

def clear_app_context_cache() -> None:
    """Clear the cached ``AppContext`` and config to force reload next time."""
    if hasattr(app, "_context_cache"):
        app._context_cache.clear()
    if hasattr(app, "_config_cache"):
        app._config_cache.clear()

clear_context_bound_auth_providers

clear_context_bound_auth_providers() -> None

Drop in-memory auth providers so the next use rebuilds from the active context.

Providers are keyed only by name in the process-global registry. After a context switch, stale instances retain the previous context's audience and other settings. Unregistering discards in-memory objects only; it does not call logout or delete context-isolated credential caches.

Source code in qsh/cli/app.py

def clear_context_bound_auth_providers() -> None:
    """Drop in-memory auth providers so the next use rebuilds from the active context.

    Providers are keyed only by name in the process-global registry. After a
    context switch, stale instances retain the previous context's audience and
    other settings. Unregistering discards in-memory objects only; it does not
    call logout or delete context-isolated credential caches.
    """
    from qlam_core.auth.registry import auth_registry

    for provider_name in list(auth_registry.list_providers()):
        auth_registry.unregister_provider(provider_name)

cli_main

cli_main() -> None

Main entry point that loads plugins only when needed.

This function may terminate the process with a non-zero exit code on error.

Source code in qsh/cli/app.py

def cli_main() -> None:
    """Main entry point that loads plugins only when needed.

    This function may terminate the process with a non-zero exit code on error.
    """
    try:
        _run_cli()
    except KeyboardInterrupt:
        _handle_keyboard_interrupt()
    except AuthConfigurationError as e:
        _handle_auth_configuration_error(e)
    except APIError as e:
        _handle_api_error(e)
    except QlamCoreError as e:
        _handle_qshcli_error(e)
    except httpx.RequestError as e:
        _handle_httpx_request_error(e)
    except Exception as e:  # noqa: BLE001
        # CLI boundary: last-resort catch-all. We intentionally map unexpected failures
        # to ExitCode.UNKNOWN_ERROR here to keep the rest of the codebase free of
        # blanket exception handling.
        _handle_generic_exception(e)

completion_command

completion_command(shell: Annotated[str, Argument(help='Shell type: bash, zsh, fish, or powershell')]) -> None

Generate shell completion scripts for the given shell.

Parameters:

Name	Type	Description	Default
`shell`	`Annotated[str, Argument(help='Shell type: bash, zsh, fish, or powershell')]`	Target shell (`bash`, `zsh`, `fish`, or `powershell`).	required

Raises:

Type	Description
`typer.Exit`	If the shell is unsupported. Examples: qsh completion bash > ~/.qsh_completion source ~/.qsh_completion qsh completion zsh > ~/.zsh/completions/_qsh qsh completion fish > ~/.config/fish/completions/qsh.fish

Source code in qsh/cli/app.py

@app.command("completion")
def completion_command(
    shell: Annotated[str, typer.Argument(help="Shell type: bash, zsh, fish, or powershell")],
) -> None:
    """Generate shell completion scripts for the given shell.

    :param shell: Target shell (``bash``, ``zsh``, ``fish``, or ``powershell``).
    :raises typer.Exit: If the shell is unsupported.

    Examples:
        qsh completion bash > ~/.qsh_completion
        source ~/.qsh_completion

        qsh completion zsh > ~/.zsh/completions/_qsh

        qsh completion fish > ~/.config/fish/completions/qsh.fish
    """

    shell = shell.lower()
    prog_name = "qsh"

    if shell == "bash":
        completion_script = f"""
_{prog_name.upper()}_COMPLETE=bash_source {prog_name}
"""
    elif shell == "zsh":
        completion_script = f"""
#compdef {prog_name}
_{prog_name.upper()}_COMPLETE=zsh_source {prog_name}
"""
    elif shell == "fish":
        completion_script = f"""
complete -c {prog_name} -f -a "(env _{prog_name.upper()}_COMPLETE=fish_source {prog_name})"
"""
    elif shell == "powershell":
        completion_script = f"""
Register-ArgumentCompleter -Native -CommandName {prog_name} -ScriptBlock {{
    param($wordToComplete, $commandAst, $cursorPosition)
    $env:_{prog_name.upper()}_COMPLETE="powershell_source"
    $result = & {prog_name} 2>&1
    $env:_{prog_name.upper()}_COMPLETE=""
    $result
}}
"""
    else:
        console.print(
            f"[red]Error: Unsupported shell '{shell}'. Supported shells: bash, zsh, fish, powershell[/red]"
        )
        raise typer.Exit(1)

    # Output the completion script
    print(completion_script.strip())

context_list

context_list(output: str | None = typer.Option(None, '-o', '--output', help='Output format (json, table).')) -> None

List all configured contexts.

Source code in qsh/cli/app.py

@_context_app.command("list")
def context_list(
    output: str | None = typer.Option(None, "-o", "--output", help="Output format (json, table)."),
) -> None:
    """List all configured contexts."""
    from qsh.cli.io import render

    ctx = create_app_context()
    config = ctx.config
    active_name = config.context_name

    rows: list[dict] = []
    for c in config.contexts:
        row: dict = {
            "name": c.name,
            "active": "*" if c.name == active_name else "",
            "qpu": c.qpu,
        }
        if c.defaults and c.defaults.api_base_url:
            row["api_base_url"] = str(c.defaults.api_base_url)
        rows.append(row)

    render(rows, output or ctx.effective_output_format)

context_set

context_set(name: str = typer.Argument(..., help='Context name to set as active.')) -> None

Set the active context in config and the current process.

Updates sticky session state (including a startup --context override) and clears cached AppContext config. When the effective context changes, it unregisters in-memory auth providers so the next auth use rebuilds from the new context without logout.

Source code in qsh/cli/app.py

@_context_app.command("set")
def context_set(
    name: str = typer.Argument(..., help="Context name to set as active."),
) -> None:
    """Set the active context in config and the current process.

    Updates sticky session state (including a startup ``--context`` override)
    and clears cached AppContext config. When the effective context changes,
    it unregisters in-memory auth providers so the next auth use rebuilds from
    the new context without logout.
    """
    from qlam_core.config.config import Config

    config = Config.load()

    available = config.context_names
    if name not in available:
        typer.echo(f"Error: context '{name}' not found.", err=True)
        typer.echo(f"Available contexts: {', '.join(available)}", err=True)
        raise typer.Exit(code=1)

    state = getattr(app, "state", None)
    effective_context = state.get("context") if state else None
    if effective_context is None:
        effective_context = config.context_name

    config.set_context(name)
    config.save()

    if state is None:
        app.state = {}
    app.state["context"] = name
    clear_app_context_cache()
    if effective_context != name:
        clear_context_bound_auth_providers()

    typer.echo(f"Switched to context '{name}'.")

context_show

context_show(output: str | None = typer.Option(None, '-o', '--output', help='Output format (json, table).')) -> None

Display the current active context name.

Source code in qsh/cli/app.py

@_context_app.command("show")
def context_show(
    output: str | None = typer.Option(None, "-o", "--output", help="Output format (json, table)."),
) -> None:
    """Display the current active context name."""
    from qsh.cli.io import render

    ctx = create_app_context()
    result = {"current_context": ctx.config.context_name}
    render(result, output or ctx.effective_output_format)

create_app_context

create_app_context() -> 'AppContext'

Create and cache an AppContext populated from current CLI state.

The context and settings are cached across invocations during a single process run to avoid repeated disk I/O.

Returns:

Type	Description
`'AppContext'`	Initialized `AppContext` instance.

Source code in qsh/cli/app.py

def create_app_context() -> "AppContext":
    """Create and cache an ``AppContext`` populated from current CLI state.

    The context and settings are cached across invocations during a single
    process run to avoid repeated disk I/O.

    :return: Initialized ``AppContext`` instance.
    """
    from qlam_core.common.context import AppContext

    state = getattr(app, "state", {})
    cache_key = f"context_{state.get('context', 'default')}_{state.get('verbose', False)}"

    if hasattr(app, "_context_cache") and cache_key in app._context_cache:
        from qlam_core.common.visibility import Visibility

        cached_context = app._context_cache[cache_key]
        # Update dynamic properties that may change between calls
        output = state.get("output")
        cached_context.output_format = output.value if output else None
        cached_context.wrap = state.get("wrap", False)
        cached_context.visibility = Visibility.PRIVATE if state.get("private") else None
        # Reset on every hit so one REPL command's --auth doesn't stick to the cached context.
        cached_context.auth_provider_name = state.get("auth")
        return cached_context

    main_logger = logging.getLogger("qsh")
    context_logger = main_logger.getChild("context")

    config_cache_key = f"config_{state.get('context', 'default')}"
    if not hasattr(app, "_config_cache"):
        app._config_cache = {}

    if config_cache_key not in app._config_cache:
        from qlam_core.config.config import Config

        config = Config.load(state.get("context"))
        app._config_cache[config_cache_key] = config
    else:
        config = app._config_cache[config_cache_key]

    from qlam_core.common.visibility import Visibility

    context = AppContext(
        context_name=state.get("context"),
        output_format=state.get("output").value if state.get("output") else None,
        verbose=state.get("verbose", False),
        wrap=state.get("wrap", False),
        logger=context_logger,
        cached_config=config,
        visibility=Visibility.PRIVATE if state.get("private") else None,
        auth_provider_name=state.get("auth"),
    )

    if not hasattr(app, "_context_cache"):
        app._context_cache = {}
    app._context_cache[cache_key] = context

    return context

help_command

help_command(ctx: Context) -> None

Show help for QSH commands (equivalent to qsh --help).

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	Typer context (unused; kept for parity with Typer conventions).	required

Source code in qsh/cli/app.py

@app.command("help")
def help_command(ctx: typer.Context) -> None:
    """Show help for QSH commands (equivalent to ``qsh --help``).

    :param ctx: Typer context (unused; kept for parity with Typer conventions).
    """
    click_app = typer.main.get_command(app)
    help_ctx = click_app.make_context("qsh", ["--help"], resilient_parsing=True)
    help_text = click_app.get_help(help_ctx)
    console.print(help_text)

load_plugins

load_plugins(app: Typer, ctx_provider: Callable[[], 'AppContext']) -> None

Lazy wrapper around plugin loading.

This keeps plugin discovery imports out of module import time for fast built-ins like qsh version and qsh completion.

Source code in qsh/cli/app.py

def load_plugins(app: typer.Typer, ctx_provider: Callable[[], "AppContext"]) -> None:
    """Lazy wrapper around plugin loading.

    This keeps plugin discovery imports out of module import time for fast built-ins
    like ``qsh version`` and ``qsh completion``.
    """
    from qsh.cli.wiring import load_plugins as _load_plugins

    _load_plugins(app, ctx_provider)

main

main() -> None

Entry point for the qsh command.

Source code in qsh/cli/app.py

def main() -> None:
    """Entry point for the qsh command."""
    cli_main()

repl_command

repl_command() -> None

Start an interactive REPL session.

The REPL provides an interactive shell where you can run QSH commands without having to type 'qsh' before each command. It supports tab completion and maintains the current context config.

Examples: qsh repl # Start interactive shell qsh --context prod repl # Start REPL with specific context

Source code in qsh/cli/app.py

@app.command(name="repl")
def repl_command() -> None:
    """Start an interactive REPL session.

    The REPL provides an interactive shell where you can run QSH commands
    without having to type 'qsh' before each command. It supports tab
    completion and maintains the current context config.

    Examples:
        qsh repl                    # Start interactive shell
        qsh --context prod repl     # Start REPL with specific context
    """
    from qsh.cli.repl import start_repl

    start_repl(app, console)

setup_logging

setup_logging(verbose: bool = False) -> logging.Logger

Configure logging with a rich handler and return the main logger.

Parameters:

Name	Type	Description	Default
`verbose`	`bool`	Enable verbose log level (DEBUG) when True, otherwise WARNING.	`False`

Returns:

Type	Description
`Logger`	Configured logger named `qsh`.

Source code in qsh/cli/app.py

def setup_logging(verbose: bool = False) -> logging.Logger:
    """Configure logging with a rich handler and return the main logger.

    :param verbose: Enable verbose log level (DEBUG) when True, otherwise WARNING.
    :return: Configured logger named ``qsh``.
    """
    level = logging.DEBUG if verbose else logging.WARNING

    # Create main logger
    logger = logging.getLogger("qsh")
    logger.setLevel(level)

    # Remove any existing handlers to avoid duplicates
    for handler in logger.handlers[:]:
        logger.removeHandler(handler)

    # Add rich handler
    handler = RichHandler(console=console, rich_tracebacks=True, show_path=False)
    handler.setFormatter(logging.Formatter("%(message)s"))
    logger.addHandler(handler)

    # Prevent propagation to root logger
    logger.propagate = False

    return logger

version_command

version_command() -> None

Show version information.

Source code in qsh/cli/app.py

@app.command("version")
def version_command() -> None:
    """Show version information."""
    from qsh.utils.version import get_version

    console.print(f"qsh-client version {get_version()}")