lightning-sdk 2025.12.17__py3-none-any.whl → 2026.1.27__py3-none-any.whl

lightning_sdk/cli/legacy/download.py

@@ -12,6 +12,7 @@ from lightning_sdk.api.lit_container_api import LitContainerApi
 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.exceptions import DeprecatedCommand, DeprecatedError
 from lightning_sdk.models import download_model
 from lightning_sdk.studio import Studio
 from lightning_sdk.utils.resolve import _get_authed_user
@@ -63,134 +64,64 @@ def model(name: str, download_dir: str = ".") -> None:
     )
 
 
-@download.command(name="folder")
-@click.argument("path")
+@download.command(
+    name="folder",
+    cls=DeprecatedCommand,
+    message="Studio downloads via 'lightning download folder' are deprecated. Use 'lightning studio cp -r' instead.",
+)
+@click.argument("path", required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "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, "
-        "a menu filtered studios will be shown for final selection."
-    ),
+    hidden=True,
 )
 @click.option(
     "--teamspace",
     default=None,
-    help="The teamspace the drive folder is part of. Should be of format <OWNER>/<TEAMSPACE_NAME>.",
+    hidden=True,
 )
 @click.option(
     "--local-path",
     "--local_path",
-    default=".",
-    type=click.Path(file_okay=False, dir_okay=True),
-    help="The path to the directory you want to download the folder to.",
+    default=None,
+    hidden=True,
 )
 def folder(
     path: str = "", studio: Optional[str] = None, teamspace: Optional[str] = None, local_path: str = "."
 ) -> None:
-    """Download a folder from a Studio or a Teamspace drive folder.
-
-    Example:
-      lightning download folder PATH
-
-    PATH: The relative path within the Studio or drive folder you want to download.
-    Defaults to the entire Studio or drive folder.
-    """
-    local_path = Path(local_path)
-    if not local_path.is_dir():
-        raise NotADirectoryError(f"'{local_path}' is not a directory")
-
-    if studio and teamspace:
-        raise ValueError("Either --studio or --teamspace must be provided, not both")
-
-    if studio:
-        path = _expand_remote_path(path)
-        resolved_downloader = _resolve_studio(studio)
-    elif teamspace:
-        menu = TeamspacesMenu()
-        resolved_downloader = menu(teamspace)
-    else:
-        raise ValueError("Either --studio or --teamspace must be provided")
-
-    if not path:
-        local_path /= resolved_downloader.name
-        path = ""
-
-    try:
-        if not path and teamspace:
-            raise FileNotFoundError()
-        resolved_downloader.download_folder(remote_path=path, target_path=str(local_path))
-    except Exception as e:
-        raise StudioCliError(
-            f"Could not download the folder from the given Studio {studio} or Teamspace {teamspace}. "
-            "Please contact Lightning AI directly to resolve this issue."
-        ) from e
+    """[DEPRECATED] Use 'lightning studio cp -r' instead."""
+    raise DeprecatedError(
+        "Studio downloads via 'lightning download folder' are deprecated. Use 'lightning studio cp -r' instead."
+    )
 
 
-@download.command(name="file")
-@click.argument("path")
+@download.command(
+    name="file",
+    cls=DeprecatedCommand,
+    message="Studio downloads via 'lightning download file' are deprecated. Use 'lightning studio cp' instead.",
+)
+@click.argument("path", required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "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, "
-        "a menu filtered studios will be shown for final selection."
-    ),
+    hidden=True,
 )
 @click.option(
     "--teamspace",
     default=None,
-    help="The teamspace the file is part of. Should be of format <OWNER>/<TEAMSPACE_NAME>.",
+    hidden=True,
 )
 @click.option(
     "--local-path",
     "--local_path",
-    default=".",
-    type=click.Path(file_okay=False, dir_okay=True),
-    help="The path to the directory you want to download the file to.",
+    default=None,
+    hidden=True,
 )
 def file(path: str = "", studio: Optional[str] = None, teamspace: Optional[str] = None, local_path: str = ".") -> None:
-    """Download a file from a Studio or Teamspace drive file.
-
-    Example:
-      lightning download file PATH
-
-    PATH: The relative path to the file within the Studio or Teamspace drive file you want to download.
-    """
-    local_path = Path(local_path)
-    if not local_path.is_dir():
-        raise NotADirectoryError(f"'{local_path}' is not a directory")
-
-    if studio and teamspace:
-        raise ValueError("Either --studio or --teamspace must be provided, not both")
-
-    if studio:
-        resolved_downloader = _resolve_studio(studio)
-    elif teamspace:
-        menu = TeamspacesMenu()
-        resolved_downloader = menu(teamspace)
-    else:
-        raise ValueError("Either --studio or --teamspace must be provided")
-
-    if not path:
-        local_path /= resolved_downloader.name
-        path = ""
-
-    try:
-        if not path:
-            raise FileNotFoundError()
-        resolved_downloader.download_file(remote_path=path, file_path=str(local_path / os.path.basename(path)))
-    except Exception as e:
-        raise StudioCliError(
-            f"Could not download the file from the given Studio {studio} or Teamspace {teamspace}. "
-            "Please contact Lightning AI directly to resolve this issue."
-        ) from e
+    """[DEPRECATED] Use 'lightning studio cp' instead."""
+    raise DeprecatedError(
+        "Studio downloads via 'lightning download file' are deprecated. Use 'lightning studio cp' instead."
+    )
 
 
 @download.command(name="container")

lightning_sdk/cli/legacy/run.py

@@ -50,6 +50,15 @@ def run() -> None:
     help="The organization owning the teamspace (if any). Defaults to the current organization.",
 )
 @click.option("--user", default=None, help="The user owning the teamspace (if any). Defaults to the current user.")
+@click.option(
+    "--cloud-provider",
+    "--cloud_provider",
+    default=None,
+    help=(
+        "The provider to create the studio on. If set, must be in agreement with the provider from the "
+        "cloud_account (if specified)."
+    ),
+)
 @click.option(
     "--cloud-account",
     "--cloud_account",
@@ -96,7 +105,7 @@ def run() -> None:
 )
 @click.option(
     "--entrypoint",
-    default="sh -c",
+    default=None,
     show_default=True,
     help=(
         "The entrypoint of your docker container. "
@@ -141,6 +150,7 @@ def job(
     teamspace: Optional[str] = None,
     org: Optional[str] = None,
     user: Optional[str] = None,
+    cloud_provider: Optional[str] = None,
     cloud_account: Optional[str] = None,
     env: Sequence[str] = (),
     interruptible: bool = False,
@@ -184,6 +194,7 @@ def job(
         teamspace=resolved_teamspace,
         org=org,
         user=user,
+        cloud_provider=cloud_provider,
         cloud_account=cloud_account,
         env=env_dict,
         interruptible=interruptible,
@@ -289,7 +300,7 @@ def job(
 )
 @click.option(
     "--entrypoint",
-    default="sh -c",
+    default=None,
     show_default=True,
     help=(
         "The entrypoint of your docker container. "

lightning_sdk/cli/legacy/upload.py

@@ -18,6 +18,7 @@ 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.constants import _LIGHTNING_DEBUG
+from lightning_sdk.exceptions import DeprecatedCommand, DeprecatedError
 from lightning_sdk.models import upload_model as _upload_model
 from lightning_sdk.studio import Studio
 from lightning_sdk.utils.resolve import _get_authed_user
@@ -54,56 +55,48 @@ def model(name: str, path: str = ".", cloud_account: Optional[str] = None) -> No
     _upload_model(name, path, cloud_account=cloud_account)
 
 
-@upload.command("folder")
-@click.argument("path", type=click.Path(exists=True))
-@click.option(
-    "--studio",
-    default=None,
-    help=(
-        "The name of the studio to upload to. "
-        "Will show a menu for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME>"
-    ),
+@upload.command(
+    name="folder",
+    cls=DeprecatedCommand,
+    message="Studio uploads via 'lightning upload folder' are deprecated. Use 'lightning studio cp -r' instead.",
 )
+@click.argument("path", type=click.Path(), required=False, nargs=-1)
+@click.option("--studio", default=None, hidden=True)
 @click.option(
     "--remote-path",
     "--remote_path",
     default=None,
-    help=(
-        "The path where the uploaded file should appear on your Studio. "
-        "Has to be within your Studio's home directory and will be relative to that. "
-        "If not specified, will use the name of the folder you want to upload and place it in your home directory."
-    ),
+    hidden=True,
 )
 def folder(path: str, studio: Optional[str], remote_path: Optional[str]) -> None:
-    """Upload a folder to a Studio."""
-    _folder(path=path, studio=studio, remote_path=remote_path)
+    """[DEPRECATED] Use 'lightning studio cp -r' instead."""
+    raise DeprecatedError(
+        "Studio uploads via 'lightning upload folder' are deprecated. Use 'lightning studio cp -r' instead."
+    )
 
 
-@upload.command("file")
-@click.argument("path", type=click.Path(exists=True))
+@upload.command(
+    name="file",
+    cls=DeprecatedCommand,
+    message="Studio uploads via 'lightning upload file' are deprecated. Use 'lightning studio cp' instead.",
+)
+@click.argument("path", type=click.Path(), required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "The name of the studio to upload to. "
-        "Will show a menu for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME>"
-    ),
+    hidden=True,
 )
 @click.option(
     "--remote-path",
     "--remote_path",
     default=None,
-    help=(
-        "The path where the uploaded file should appear on your Studio. "
-        "Has to be within your Studio's home directory and will be relative to that. "
-        "If not specified, will use the name of the file you want to upload and place it in your home directory."
-    ),
+    hidden=True,
 )
 def file(path: str, studio: Optional[str] = None, remote_path: Optional[str] = None) -> None:
-    """Upload a file to a Studio."""
-    _file(path=path, studio=studio, remote_path=remote_path)
+    """[DEPRECATED] Use 'lightning studio cp' instead."""
+    raise DeprecatedError(
+        "Studio uploads via 'lightning upload file' are deprecated. Use 'lightning studio cp' instead."
+    )
 
 
 @upload.command("container")

lightning_sdk/cli/studio/__init__.py

@@ -10,6 +10,8 @@ def register_commands(group: click.Group) -> None:
     from lightning_sdk.cli.studio.create import create_studio
     from lightning_sdk.cli.studio.delete import delete_studio
     from lightning_sdk.cli.studio.list import list_studios
+    from lightning_sdk.cli.studio.ls import ls_studio
+    from lightning_sdk.cli.studio.rm import rm_studio_file
     from lightning_sdk.cli.studio.ssh import ssh_studio
     from lightning_sdk.cli.studio.start import start_studio
     from lightning_sdk.cli.studio.stop import stop_studio
@@ -24,3 +26,5 @@ def register_commands(group: click.Group) -> None:
     group.add_command(switch_studio)
     group.add_command(connect_studio)
     group.add_command(cp_studio_file)
+    group.add_command(ls_studio)
+    group.add_command(rm_studio_file)

lightning_sdk/cli/studio/cp.py

@@ -2,22 +2,20 @@
 
 import os
 from pathlib import Path
-from typing import Optional, TypedDict
+from typing import Optional
 
 import click
 from rich.console import Console
 
 from lightning_sdk.api.utils import _get_cloud_url
-from lightning_sdk.cli.utils.owner_selection import OwnerMenu
-from lightning_sdk.cli.utils.studio_selection import StudiosMenu
-from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
-from lightning_sdk.studio import Studio
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
 
 
 @click.command("cp")
 @click.argument("source", nargs=1)
 @click.argument("destination", nargs=1)
-def cp_studio_file(source: str, destination: str, teamspace: Optional[str] = None) -> None:
+@click.option("-r", "--recursive", is_flag=True, help="Copy directories recursively")
+def cp_studio_file(source: str, destination: str, teamspace: Optional[str] = None, recursive: bool = False) -> None:
     """Copy a Studio file.
 
     SOURCE: Source file to copy from. For Studio files, use the format lit://<owner>/<my-teamspace>/studios/<my-studio>/<filepath>.
@@ -26,70 +24,29 @@ def cp_studio_file(source: str, destination: str, teamspace: Optional[str] = Non
 
     Example:
         lightning studio cp source.txt lit://<owner>/<my-teamspace>/studios/<my-studio>/destination.txt
+        lightning studio cp -r source_folder/ lit://<owner>/<my-teamspace>/studios/<my-studio>/destination_folder/
 
     """
-    return cp_impl(source=source, destination=destination)
+    return cp_impl(source=source, destination=destination, recursive=recursive)
 
 
-def cp_impl(source: str, destination: str) -> None:
+def cp_impl(source: str, destination: str, recursive: bool = False) -> None:
     if "lit://" in source and "lit://" in destination:
         raise ValueError("Both source and destination cannot be Studio files.")
     elif "lit://" not in source and "lit://" not in destination:
         raise ValueError("Either source or destination must be a Studio file.")
     elif "lit://" in source:
         # Download from Studio to local
-        cp_download(studio_path=source, local_path=destination)
+        cp_download(studio_path=source, local_path=destination, recursive=recursive)
     else:
         # Upload from local to Studio
-        cp_upload(local_file_path=source, studio_file_path=destination)
-
-
-class StudioPathResult(TypedDict):
-    owner: Optional[str]
-    teamspace: Optional[str]
-    studio: Optional[str]
-    destination: Optional[str]
-
-
-def parse_studio_path(studio_path: str) -> StudioPathResult:
-    path_string = studio_path.removeprefix("lit://")
-    if not path_string:
-        raise ValueError("Studio path cannot be empty after prefix")
-
-    result: StudioPathResult = {"owner": None, "teamspace": None, "studio": None, "destination": None}
-
-    if "/studios/" in path_string:
-        prefix_part, suffix_part = path_string.split("/studios/", 1)
-
-        # org and teamspace
-        if prefix_part:
-            org_ts_components = prefix_part.split("/")
-            if len(org_ts_components) == 2:
-                result["owner"], result["teamspace"] = org_ts_components
-            elif len(org_ts_components) == 1:
-                result["teamspace"] = org_ts_components[0]
-            else:
-                raise ValueError(f"Invalid format: '{prefix_part}'")
-
-        # studio and destination
-        path_parts = suffix_part.split("/")
-
-    else:
-        # studio and destination
-        path_parts = path_string.split("/")
-
-    if not path_parts or len(path_parts) < 2:
-        raise ValueError("Invalid: Missing studio name.")
-
-    result["studio"] = path_parts[0]
-    result["destination"] = "/".join(path_parts[1:])
-
-    return result
+        cp_upload(local_file_path=source, studio_file_path=destination, recursive=recursive)
 
 
 def cp_upload(
     local_file_path: str,
     studio_file_path: str,
+    recursive: bool = False,
 ) -> None:
     console = Console()
     if not Path(local_file_path).exists():
@@ -103,6 +60,8 @@ def cp_upload(
     console.print(f"Uploading to {selected_studio.teamspace.name}/{selected_studio.name}")
 
     if Path(local_file_path).is_dir():
+        if not recursive:
+            raise ValueError(f"'{local_file_path}' is a directory. Use -r flag to copy directories recursively.")
         selected_studio.upload_folder(local_file_path, studio_path_result["destination"])
     else:
         if studio_file_path.endswith(("/", "\\")):
@@ -126,6 +85,7 @@ def cp_upload(
 def cp_download(
     studio_path: str,
     local_path: str,
+    recursive: bool = False,
 ) -> None:
     console = Console()
     studio_path_result = parse_studio_path(studio_path)
@@ -146,8 +106,18 @@ def cp_download(
 
     console.print(f"Downloading from {selected_studio.teamspace.name}/{selected_studio.name}")
     if path_info["type"] == "directory":
+        if not recursive:
+            raise ValueError(
+                f"'{studio_path_result['destination']}' is a directory. Use -r flag to copy directories recursively."
+            )
         folder_name = os.path.basename(studio_path_result["destination"].rstrip("/"))
-        target_path = os.path.join(local_path, folder_name)
+        if local_path in ("./", "."):
+            if folder_name == "":
+                # handle root directory case (e.g. lit://lightning-ai/gpt-oss/studios/manual-lime-ylu2/)
+                folder_name = selected_studio.name
+            target_path = os.path.join(local_path, folder_name)
+        else:
+            target_path = local_path
 
         selected_studio.download_folder(studio_path_result["destination"], target_path)
         console.print(f"See your folder at {target_path}")
@@ -161,14 +131,3 @@ def cp_download(
         os.makedirs(os.path.dirname(target_path), exist_ok=True)
         selected_studio.download_file(studio_path_result["destination"], target_path)
         console.print(f"See your file at {target_path}")
-
-
-def resolve_studio(studio_name: Optional[str], teamspace: Optional[str], owner: Optional[str]) -> Studio:
-    owner_menu = OwnerMenu()
-    resolved_owner = owner_menu(owner=owner)
-
-    teamspace_menu = TeamspacesMenu(resolved_owner)
-    resolved_teamspace = teamspace_menu(teamspace=teamspace)
-
-    studio_menu = StudiosMenu(resolved_teamspace)
-    return studio_menu(studio=studio_name)

lightning_sdk/cli/studio/ls.py

@@ -0,0 +1,57 @@
+"""Studio ls command."""
+
+import click
+
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
+
+
+@click.command("ls")
+@click.argument("path", nargs=1)
+def ls_studio(path: str) -> None:
+    """List contents of a directory in Studio.
+
+    PATH: Studio path in the format
+            lit://<owner>/<teamspace>/studios/<studio>/<directory-path>
+
+    Example:
+        lightning studio ls lit://<owner>/<my-teamspace>/studios/<my-studio>/data
+
+    """
+    return ls_impl(path=path)
+
+
+def ls_impl(path: str) -> None:
+    if not path.startswith("lit://"):
+        raise ValueError("Path must be a Studio path starting with 'lit://'.")
+
+    studio_path_result = parse_studio_path(path)
+    selected_studio = resolve_studio(
+        studio_path_result["studio"], studio_path_result["teamspace"], studio_path_result["owner"]
+    )
+
+    path_info = selected_studio._studio_api.get_path_info(
+        selected_studio._studio.id, selected_studio._teamspace.id, path=studio_path_result["destination"]
+    )
+
+    if not path_info["exists"]:
+        raise FileNotFoundError(
+            f"The provided path does not exist in the studio: {studio_path_result['destination']} "
+            "Note that empty folders may not be detected as existing."
+        )
+
+    if path_info["type"] == "file":
+        # print the file name if it's a file (bash-like behavior)
+        print(studio_path_result["destination"])
+        return
+
+    tree = selected_studio._studio_api.get_tree(
+        selected_studio._studio.id, selected_studio._teamspace.id, path=studio_path_result["destination"]
+    )
+
+    tree_items = tree.get("tree", [])
+
+    for item in tree_items:
+        name = item.get("path", "")
+        if item.get("type") == "tree":
+            name += "/"
+        print(name)

lightning_sdk/cli/studio/rm.py

@@ -0,0 +1,71 @@
+"""Studio rm command."""
+
+import click
+from rich.console import Console
+
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
+from lightning_sdk.studio import Studio
+
+
+@click.command("rm")
+@click.argument("path", nargs=1)
+@click.option("-r", "--recursive", is_flag=True, help="Remove directories recursively")
+@click.option("-f", "--force", is_flag=True, help="Ignore nonexistent files, never prompt")
+def rm_studio_file(path: str, recursive: bool = False, force: bool = False) -> None:
+    """Remove a Studio file or directory.
+
+    PATH: Studio path to remove. Use the format lit://<owner>/<my-teamspace>/studios/<my-studio>/<filepath>.
+
+    Example:
+        lightning studio rm lit://<owner>/<my-teamspace>/studios/<my-studio>/file.txt
+        lightning studio rm -r lit://<owner>/<my-teamspace>/studios/<my-studio>/folder/
+
+    """
+    return rm_impl(path=path, recursive=recursive, force=force)
+
+
+def rm_impl(path: str, recursive: bool = False, force: bool = False) -> None:
+    if "lit://" not in path:
+        raise ValueError("Path must be a Studio path starting with 'lit://'.")
+
+    console = Console()
+    studio_path_result = parse_studio_path(path)
+
+    selected_studio = resolve_studio(
+        studio_path_result["studio"], studio_path_result["teamspace"], studio_path_result["owner"]
+    )
+
+    # check if file/folder exists
+    path_info = selected_studio._studio_api.get_path_info(
+        selected_studio._studio.id, selected_studio._teamspace.id, path=studio_path_result["destination"]
+    )
+
+    if not path_info["exists"]:
+        if force:
+            # silently ignore nonexistent files with -f flag
+            return
+        raise FileNotFoundError(
+            f"The provided path does not exist in the studio: '{studio_path_result['destination']}'. "
+            "Note that empty folders may not be detected as existing."
+        )
+
+    console.print(f"Removing from {selected_studio.teamspace.name}/{selected_studio.name}")
+
+    if path_info["type"] == "directory":
+        if not recursive:
+            raise ValueError(
+                f"'{studio_path_result['destination']}' is a directory. Use -r flag to remove directories recursively."
+            )
+        rm_folder(selected_studio=selected_studio, path=studio_path_result["destination"], console=console)
+    else:
+        rm_file(selected_studio=selected_studio, path=studio_path_result["destination"], console=console)
+
+
+def rm_file(selected_studio: Studio, path: str, console: Console) -> None:
+    selected_studio._studio_api.remove_file(selected_studio._studio.id, selected_studio._teamspace.id, path)
+    console.print(f"Removed file: {path}")
+
+
+def rm_folder(selected_studio: Studio, path: str, console: Console) -> None:
+    selected_studio._studio_api.remove_folder(selected_studio._studio.id, selected_studio._teamspace.id, path)
+    console.print(f"Removed directory: {path}")