lightning-sdk 2025.8.6rc2__py3-none-any.whl → 2025.11.5__py3-none-any.whl

lightning_sdk/cli/entrypoint.py

@@ -1,69 +1,38 @@
+"""New Lightning CLI entrypoint with organized command groups."""
+
+import os
 import sys
-import traceback
-from types import TracebackType
-from typing import Type
 
 import click
-from rich.console import Console, Group
-from rich.panel import Panel
-from rich.syntax import Syntax
-from rich.text import Text
 
 from lightning_sdk import __version__
 from lightning_sdk.api.studio_api import _cloud_url
-from lightning_sdk.cli.ai_hub import aihub
-from lightning_sdk.cli.coloring import CustomHelpFormatter
-from lightning_sdk.cli.configure import configure
-from lightning_sdk.cli.connect import connect
-from lightning_sdk.cli.create import create
-from lightning_sdk.cli.delete import delete
-from lightning_sdk.cli.deploy.serve import deploy
-from lightning_sdk.cli.docker_cli import dockerize
-from lightning_sdk.cli.download import download
-from lightning_sdk.cli.generate import generate
-from lightning_sdk.cli.inspection import inspect
-from lightning_sdk.cli.list import list_cli
-from lightning_sdk.cli.open import open
-from lightning_sdk.cli.run import run
-from lightning_sdk.cli.start import start
-from lightning_sdk.cli.stop import stop
-from lightning_sdk.cli.switch import switch
-from lightning_sdk.cli.upload import upload
-from lightning_sdk.constants import _LIGHTNING_DEBUG
-from lightning_sdk.lightning_cloud.login import Auth
-
-
-def _notify_exception(exception_type: Type[BaseException], value: BaseException, tb: TracebackType) -> None:
-    """CLI won't show tracebacks, just print the exception message."""
-    console = Console()
-
-    message = str(value.args[0]) if value.args else str(value) or "An unknown error occurred"
 
-    error_text = Text()
-    error_text.append(f"{exception_type.__name__}: ", style="bold red")
-    error_text.append(message, style="white")
-
-    renderables = [error_text]
-
-    if _LIGHTNING_DEBUG:
-        tb_text = "".join(traceback.format_exception(exception_type, value, tb))
-        renderables.append(Text("\n\nFull traceback:\n", style="bold yellow"))
-        renderables.append(Syntax(tb_text, "python", theme="monokai", line_numbers=False, word_wrap=True))
-    else:
-        renderables.append(Text("\n\n🐞 To view the full traceback, set: LIGHTNING_DEBUG=1"))
-
-    renderables.append(Text("\n📘 Need help? Run: lightning <command> --help", style="cyan"))
-
-    console.print(Panel(Group(*renderables), title="⚡ Lightning CLI Error", border_style="red"))
+# Import legacy groups directly from groups.py
+from lightning_sdk.cli.groups import (
+    base_studio,
+    config,
+    # job,
+    license,
+    # mmt,
+    studio,
+    vm,
+)
+from lightning_sdk.cli.utils import CustomHelpFormatter
+from lightning_sdk.cli.utils.logging import CommandLoggingGroup, logging_excepthook
+from lightning_sdk.lightning_cloud.login import Auth
 
 
-@click.group(name="lightning", help="Command line interface (CLI) to interact with/manage Lightning AI Studios.")
+@click.group(
+    name="lightning",
+    help="Command line interface (CLI) to interact with/manage Lightning AI Studios.",
+    cls=CommandLoggingGroup,
+)
 @click.version_option(__version__, message="Lightning CLI version %(version)s")
 def main_cli() -> None:
-    sys.excepthook = _notify_exception
+    sys.excepthook = logging_excepthook
 
 
-# colorful help messages
 main_cli.context_class.formatter_class = CustomHelpFormatter
 
 
@@ -86,24 +55,55 @@ def logout() -> None:
     auth.clear()
 
 
-# additional commands
-main_cli.add_command(aihub)
-main_cli.add_command(configure)
-main_cli.add_command(connect)
-main_cli.add_command(create)
-main_cli.add_command(delete)
-main_cli.add_command(dockerize)
-main_cli.add_command(download)
-main_cli.add_command(generate)
-main_cli.add_command(inspect)
-main_cli.add_command(list_cli)
-main_cli.add_command(run)
-main_cli.add_command(deploy)
-main_cli.add_command(start)
-main_cli.add_command(stop)
-main_cli.add_command(switch)
-main_cli.add_command(upload)
-main_cli.add_command(open)
+# Add new command groups
+main_cli.add_command(config)
+# main_cli.add_command(job)
+# main_cli.add_command(mmt)
+main_cli.add_command(studio)
+main_cli.add_command(vm)
+main_cli.add_command(base_studio)
+main_cli.add_command(license)
+
+if os.environ.get("LIGHTNING_EXPERIMENTAL_CLI_ONLY", "0") != "1":
+    #### LEGACY COMMANDS ####
+    # these commands are currently supported for backwards compatibility, but will potentially be removed in the future.
+    # they've grown pretty wild and provide a very inconsistent UX.
+    from lightning_sdk.cli.legacy.ai_hub import aihub
+    from lightning_sdk.cli.legacy.configure import configure
+    from lightning_sdk.cli.legacy.connect import connect
+    from lightning_sdk.cli.legacy.create import create
+    from lightning_sdk.cli.legacy.delete import delete
+    from lightning_sdk.cli.legacy.deploy.serve import deploy
+    from lightning_sdk.cli.legacy.docker_cli import dockerize
+    from lightning_sdk.cli.legacy.download import download
+    from lightning_sdk.cli.legacy.generate import generate
+    from lightning_sdk.cli.legacy.inspection import inspect
+    from lightning_sdk.cli.legacy.list import list_cli
+    from lightning_sdk.cli.legacy.open import open as open_cmd
+    from lightning_sdk.cli.legacy.run import run
+    from lightning_sdk.cli.legacy.start import start
+    from lightning_sdk.cli.legacy.stop import stop
+    from lightning_sdk.cli.legacy.switch import switch
+    from lightning_sdk.cli.legacy.upload import upload
+
+    # Add old command groups
+    main_cli.add_command(aihub)
+    main_cli.add_command(configure)
+    main_cli.add_command(connect)
+    main_cli.add_command(create)
+    main_cli.add_command(delete)
+    main_cli.add_command(deploy)
+    main_cli.add_command(dockerize)
+    main_cli.add_command(download)
+    main_cli.add_command(generate)
+    main_cli.add_command(inspect)
+    main_cli.add_command(list_cli)
+    main_cli.add_command(open_cmd)
+    main_cli.add_command(run)
+    main_cli.add_command(start)
+    main_cli.add_command(stop)
+    main_cli.add_command(switch)
+    main_cli.add_command(upload)
 
 
 if __name__ == "__main__":

lightning_sdk/cli/groups.py

@@ -0,0 +1,56 @@
+"""CLI groups for organizing Lightning SDK commands."""
+
+import click
+
+from lightning_sdk.cli.base_studio import register_commands as register_base_studio_commands
+from lightning_sdk.cli.config import register_commands as register_config_commands
+from lightning_sdk.cli.job import register_commands as register_job_commands
+from lightning_sdk.cli.license import register_commands as register_license_commands
+from lightning_sdk.cli.mmt import register_commands as register_mmt_commands
+from lightning_sdk.cli.studio import register_commands as register_studio_commands
+from lightning_sdk.cli.vm import register_commands as register_vm_commands
+
+
+@click.group(name="studio")
+def studio() -> None:
+    """Manage Lightning AI Studios."""
+
+
+@click.group(name="job")
+def job() -> None:
+    """Manage Lightning AI Jobs."""
+
+
+@click.group(name="mmt")
+def mmt() -> None:
+    """Manage Lightning AI Multi-Machine Training (MMT)."""
+
+
+@click.group(name="config")
+def config() -> None:
+    """Manage Lightning SDK and CLI configuration."""
+
+
+@click.group(name="vm")
+def vm() -> None:
+    """Manage Lightning AI VMs."""
+
+
+@click.group(name="base-studio")
+def base_studio() -> None:
+    """Manage Lightning AI Base Studios."""
+
+
+@click.group(name="license")
+def license() -> None:  # noqa: A001
+    """Manage Lightning AI Product Licenses."""
+
+
+# Register config commands with the main config group
+register_job_commands(job)
+register_mmt_commands(mmt)
+register_studio_commands(studio)
+register_config_commands(config)
+register_vm_commands(vm)
+register_base_studio_commands(base_studio)
+register_license_commands(license)

lightning_sdk/cli/job/__init__.py

@@ -0,0 +1,7 @@
+"""Job CLI commands."""
+
+import click
+
+
+def register_commands(group: click.Group) -> None:
+    """Register job commands with the given group."""

lightning_sdk/cli/{clusters_menu.py → legacy/clusters_menu.py}

@@ -1,12 +1,12 @@
 import sys
-from typing import List
+from typing import List, Optional
 
 from rich.console import Console
 from simple_term_menu import TerminalMenu
 
 from lightning_sdk import Teamspace
 from lightning_sdk.api.cloud_account_api import CloudAccountApi
-from lightning_sdk.lightning_cloud.openapi import Externalv1Cluster, V1ProjectClusterBinding
+from lightning_sdk.lightning_cloud.openapi import V1ClusterType, V1ProjectClusterBinding
 
 
 class _ClustersMenu:
@@ -22,18 +22,21 @@ class _ClustersMenu:
 
         return TerminalMenu(cluster_ids, title=title, clear_menu_on_exit=True)
 
-    def _resolve_cluster(self, teamspace: Teamspace) -> Externalv1Cluster:
+    def _resolve_cluster(self, teamspace: Teamspace) -> Optional[str]:
         selected_cluster_id = None
         console = Console()
         try:
-            selected_cluster_id = self._get_cluster_from_interactive_menu(
+            selected_cluster_id = teamspace.default_cloud_account or self._get_cluster_from_interactive_menu(
                 possible_clusters=teamspace.cloud_account_objs
             )
+
             cloud_account_api = CloudAccountApi()
 
-            return cloud_account_api.get_cloud_account(
-                cluster_id=selected_cluster_id, org_id=teamspace.owner.id, project_id=teamspace.id
+            resolved_cluster_obj = cloud_account_api.get_cloud_account(
+                cloud_account_id=selected_cluster_id, org_id=teamspace.owner.id, teamspace_id=teamspace.id
             )
+
+            return None if resolved_cluster_obj.spec.cluster_type == V1ClusterType.GLOBAL else resolved_cluster_obj.id
         except KeyboardInterrupt:
             console.print("Operation cancelled by user")
             sys.exit(0)

lightning_sdk/cli/{configure.py → legacy/configure.py}

@@ -7,8 +7,8 @@ from typing import Optional, Union
 import click
 from rich.console import Console
 
-from lightning_sdk.cli.generate import _generate_ssh_config
-from lightning_sdk.cli.studios_menu import _StudiosMenu
+from lightning_sdk.cli.legacy.generate import _generate_ssh_config
+from lightning_sdk.cli.legacy.studios_menu import _StudiosMenu
 from lightning_sdk.lightning_cloud.login import Auth
 
 

lightning_sdk/cli/{connect.py → legacy/connect.py}

@@ -4,8 +4,8 @@ from typing import Optional
 
 import click
 
-from lightning_sdk.cli.configure import _configure_ssh_internal
-from lightning_sdk.cli.studios_menu import _StudiosMenu
+from lightning_sdk.cli.legacy.configure import _configure_ssh_internal
+from lightning_sdk.cli.legacy.studios_menu import _StudiosMenu
 
 
 @click.group(name="connect")

lightning_sdk/cli/{create.py → legacy/create.py}

@@ -7,10 +7,8 @@ import click
 from rich.console import Console
 
 from lightning_sdk import Machine, Studio
-from lightning_sdk.api.cloud_account_api import CloudAccountApi
-from lightning_sdk.cli.teamspace_menu import _TeamspacesMenu
+from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.machine import CloudProvider
-from lightning_sdk.utils.resolve import _resolve_deprecated_provider
 
 _MACHINE_VALUES = tuple(
     [machine.name for machine in Machine.__dict__.values() if isinstance(machine, Machine) and machine._include_in_cli]
@@ -80,16 +78,8 @@ def studio(
 
     NAME: the name of the studio to create. If already present within teamspace, will add a random suffix.
     """
-    menu = _TeamspacesMenu()
-    teamspace_resolved = menu._resolve_teamspace(teamspace)
-
-    cloud_provider = str(_resolve_deprecated_provider(cloud_provider, provider))
-
-    if cloud_provider is not None:
-        cloud_account_api = CloudAccountApi()
-        cloud_account = cloud_account_api.resolve_cloud_account(
-            teamspace_resolved.id, cloud_account, cloud_provider, teamspace_resolved.default_cloud_account
-        )
+    menu = TeamspacesMenu()
+    teamspace_resolved = menu(teamspace)
 
     # default cloud account to current studios cloud account if run from studio
     # else it will fall back to teamspace default in the backend
@@ -107,11 +97,19 @@ def studio(
         console.print(f"Studio with name {name} already exists. Using {new_name} instead.")
         name = new_name
 
-    studio = Studio(name=name, teamspace=teamspace_resolved, cloud_account=cloud_account, create_ok=True)
+    studio = Studio(
+        name=name,
+        teamspace=teamspace_resolved,
+        cloud_account=cloud_account,
+        create_ok=True,
+        cloud_provider=cloud_provider,
+        provider=provider,
+    )
 
     console.print(f"Created Studio {studio.name}.")
 
     if start is not None:
         start_machine = getattr(Machine, start, start)
+        Studio.show_progress = True
         studio.start(start_machine)
         console.print(f"Started Studio {studio.name} on machine {start}")

lightning_sdk/cli/{delete.py → legacy/delete.py}

@@ -3,9 +3,9 @@ from typing import Optional
 import click
 from rich.console import Console
 
-from lightning_sdk.cli.exceptions import StudioCliError
-from lightning_sdk.cli.job_and_mmt_action import _JobAndMMTAction
-from lightning_sdk.cli.teamspace_menu import _TeamspacesMenu
+from lightning_sdk.cli.legacy.exceptions import StudioCliError
+from lightning_sdk.cli.legacy.job_and_mmt_action import _JobAndMMTAction
+from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.lightning_cloud.openapi.rest import ApiException
 from lightning_sdk.lit_container import LitContainer
 from lightning_sdk.studio import Studio
@@ -30,8 +30,8 @@ def delete() -> None:
 def container(name: str, teamspace: Optional[str] = None) -> None:
     """Delete the docker container NAME."""
     api = LitContainer()
-    menu = _TeamspacesMenu()
-    resolved_teamspace = menu._resolve_teamspace(teamspace=teamspace)
+    menu = TeamspacesMenu()
+    resolved_teamspace = menu(teamspace=teamspace)
     try:
         api.delete_container(name, resolved_teamspace.name, resolved_teamspace.owner.name)
         Console().print(f"Container {name} deleted successfully.")

lightning_sdk/cli/{deploy → legacy/deploy}/_auth.py

@@ -10,7 +10,7 @@ from rich.prompt import Confirm
 
 from lightning_sdk import Teamspace
 from lightning_sdk.api import UserApi
-from lightning_sdk.cli.teamspace_menu import _TeamspacesMenu
+from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.lightning_cloud import env
 from lightning_sdk.lightning_cloud.login import Auth, AuthServer
 from lightning_sdk.lightning_cloud.openapi import V1CloudSpace
@@ -73,14 +73,13 @@ def authenticate(mode: _AuthMode, shall_confirm: bool = True) -> None:
 
 def select_teamspace(teamspace: Optional[str], org: Optional[str], user: Optional[str]) -> Teamspace:
     if teamspace is None:
-        user = _get_authed_user()
-        menu = _TeamspacesMenu()
-        possible_teamspaces = menu._get_possible_teamspaces(user)
+        menu = TeamspacesMenu()
+        possible_teamspaces = menu._get_possible_teamspaces(_get_authed_user())
         if len(possible_teamspaces) == 1:
             name = next(iter(possible_teamspaces.values()))["name"]
             return Teamspace(name=name, org=org, user=user)
 
-        return menu._resolve_teamspace(teamspace)
+        return menu(teamspace)
 
     return _resolve_teamspace(teamspace=teamspace, org=org, user=user)
 
@@ -180,7 +179,7 @@ class _Onboarding:
             return select_teamspace(teamspace, org, user)
 
         # Run only when user hasn't completed onboarding yet.
-        menu = _TeamspacesMenu()
+        menu = TeamspacesMenu()
         self._wait_user_onboarding()
         # Onboarding has been completed - user already selected organization if they could
         possible_teamspaces = menu._get_possible_teamspaces(self.user)

lightning_sdk/cli/{deploy → legacy/deploy}/devbox.py

@@ -12,8 +12,14 @@ from rich.prompt import Confirm
 from rich.syntax import Syntax
 
 from lightning_sdk import Machine
-from lightning_sdk.cli.deploy._auth import _AuthMode, _Onboarding, authenticate, poll_verified_status, select_teamspace
-from lightning_sdk.cli.upload import (
+from lightning_sdk.cli.legacy.deploy._auth import (
+    _AuthMode,
+    _Onboarding,
+    authenticate,
+    poll_verified_status,
+    select_teamspace,
+)
+from lightning_sdk.cli.legacy.upload import (
     _dump_current_upload_state,
     _resolve_previous_upload_state,
     _single_file_upload,

lightning_sdk/cli/{deploy → legacy/deploy}/serve.py

@@ -15,14 +15,15 @@ from rich.prompt import Confirm
 from lightning_sdk import Machine, Teamspace
 from lightning_sdk.api.lit_container_api import LitContainerApi
 from lightning_sdk.api.utils import _get_registry_url
-from lightning_sdk.cli.deploy._auth import (
+from lightning_sdk.cli.legacy.clusters_menu import _ClustersMenu
+from lightning_sdk.cli.legacy.deploy._auth import (
     _AuthMode,
     _Onboarding,
     authenticate,
     poll_verified_status,
     select_teamspace,
 )
-from lightning_sdk.cli.deploy.devbox import _handle_devbox
+from lightning_sdk.cli.legacy.deploy.devbox import _handle_devbox
 from lightning_sdk.serve import _LitServeDeployer
 
 _MACHINE_VALUES = tuple(
@@ -377,18 +378,24 @@ def _handle_cloud(
     else:
         resolved_teamspace = select_teamspace(teamspace, org, user)
 
+    lightning_containers_cloud_account = cloud_account
+    if not cloud_account:
+        clusters_menu = _ClustersMenu()
+        lightning_containers_cloud_account = clusters_menu._resolve_cluster(resolved_teamspace)
+        cloud_account = resolved_teamspace.default_cloud_account
+
     # list containers to create the project if it doesn't exist
     lit_cr = LitContainerApi()
-    lit_cr.list_containers(resolved_teamspace.id, cloud_account=cloud_account)
+    lit_cr.list_containers(resolved_teamspace.id, cloud_account=lightning_containers_cloud_account)
 
     registry_url = _get_registry_url()
     container_basename = repository.split("/")[-1]
     image = (
-        f"{registry_url}/lit-container{f'-{cloud_account}' if cloud_account is not None else ''}/"
-        f"{resolved_teamspace.owner.name}/{resolved_teamspace.name}/{container_basename}"
+        f"{registry_url}/lit-container"
+        + (f"-{lightning_containers_cloud_account}" if lightning_containers_cloud_account is not None else "")
+        + f"/{resolved_teamspace.owner.name}/{resolved_teamspace.name}/{container_basename}"
     )
 
-    cloud_account = cloud_account or resolved_teamspace.default_cloud_account
     if from_onboarding:
         thread = Thread(
             target=ls_deployer.run_on_cloud,
@@ -411,13 +418,17 @@ def _handle_cloud(
         )
         thread.start()
         console.print("🚀 Deployment started")
-        if not _upload_container(console, ls_deployer, repository, tag, resolved_teamspace, lit_cr, cloud_account):
+        if not _upload_container(
+            console, ls_deployer, repository, tag, resolved_teamspace, lit_cr, lightning_containers_cloud_account
+        ):
             thread.join()
             return
         thread.join()
         return
 
-    if not _upload_container(console, ls_deployer, repository, tag, resolved_teamspace, lit_cr, cloud_account):
+    if not _upload_container(
+        console, ls_deployer, repository, tag, resolved_teamspace, lit_cr, lightning_containers_cloud_account
+    ):
         return
 
     deployment_status = ls_deployer.run_on_cloud(

lightning_sdk/cli/{download.py → legacy/download.py}

@@ -9,12 +9,12 @@ from rich.console import Console
 
 from lightning_sdk.api.license_api import LicenseApi
 from lightning_sdk.api.lit_container_api import LitContainerApi
-from lightning_sdk.cli.exceptions import StudioCliError
-from lightning_sdk.cli.studios_menu import _StudiosMenu
-from lightning_sdk.cli.teamspace_menu import _TeamspacesMenu
+from lightning_sdk.cli.legacy.exceptions import StudioCliError
+from lightning_sdk.cli.legacy.studios_menu import _StudiosMenu
+from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.models import download_model
 from lightning_sdk.studio import Studio
-from lightning_sdk.utils.resolve import _get_authed_user, skip_studio_init
+from lightning_sdk.utils.resolve import _get_authed_user
 
 
 def _expand_remote_path(path: str) -> str:
@@ -110,8 +110,8 @@ def folder(
         path = _expand_remote_path(path)
         resolved_downloader = _resolve_studio(studio)
     elif teamspace:
-        menu = _TeamspacesMenu()
-        resolved_downloader = menu._resolve_teamspace(teamspace)
+        menu = TeamspacesMenu()
+        resolved_downloader = menu(teamspace)
     else:
         raise ValueError("Either --studio or --teamspace must be provided")
 
@@ -136,7 +136,7 @@ def folder(
     "--studio",
     default=None,
     help=(
-        "The name of the studio to upload to. "
+        "The name of the studio to download from. "
         "Will show a menu with user's owned studios for selection if not specified. "
         "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME> where the names are case-sensitive. "
         "The teamspace and studio names can be regular expressions to match, "
@@ -173,8 +173,8 @@ def file(path: str = "", studio: Optional[str] = None, teamspace: Optional[str]
     if studio:
         resolved_downloader = _resolve_studio(studio)
     elif teamspace:
-        menu = _TeamspacesMenu()
-        resolved_downloader = menu._resolve_teamspace(teamspace)
+        menu = TeamspacesMenu()
+        resolved_downloader = menu(teamspace)
     else:
         raise ValueError("Either --studio or --teamspace must be provided")
 
@@ -214,8 +214,8 @@ def download_container(
     CONTAINER: The name of the container to download.
     """
     console = Console()
-    menu = _TeamspacesMenu()
-    resolved_teamspace = menu._resolve_teamspace(teamspace)
+    menu = TeamspacesMenu()
+    resolved_teamspace = menu(teamspace)
     with console.status("Downloading container..."):
         api = LitContainerApi()
         api.download_container(container, resolved_teamspace, tag, cloud_account)
@@ -242,7 +242,7 @@ def _resolve_studio(studio: Optional[str]) -> Studio:
                     and (re.match(studio_name, st["name"]) or studio_name in st["name"]),
                     possible_studios,
                 )
-                if not possible_studios:
+                if not len(possible_studios):
                     raise ValueError(
                         f"Could not find Studio like '{studio}', please consider update your filtering pattern."
                     )
@@ -256,12 +256,11 @@ def _resolve_studio(studio: Optional[str]) -> Studio:
     # give user friendlier error message
     except Exception as e:
         raise StudioCliError(
-            f"Could not find the given Studio {studio} to upload files to. "
+            f"Could not find the given Studio {studio} to download files from. "
             "Please contact Lightning AI directly to resolve this issue."
         ) from e
 
-    with skip_studio_init():
-        return Studio(**selected_studio)
+    return Studio(**selected_studio)
 
 
 @download.command(name="licenses")