lamin_cli 1.11.0__py2.py3-none-any.whl → 1.12.0__py2.py3-none-any.whl

lamin_cli/__init__.py

@@ -6,7 +6,7 @@ The interface is defined in `__main__.py`.
 The root API here is used by LaminR to replicate the CLI functionality.
 """
 
-__version__ = "1.11.0"
+__version__ = "1.12.0"
 
 from lamindb_setup import disconnect, logout
 from lamindb_setup._connect_instance import _connect_cli as connect

lamin_cli/__main__.py

@@ -53,9 +53,7 @@ COMMAND_GROUPS = {
         {
             "name": "Configure",
             "commands": [
-                "checkout",
                 "switch",
-                "cache",
                 "settings",
                 "migrate",
             ],
@@ -112,7 +110,6 @@ else:
 
 from lamindb_setup._silence_loggers import silence_loggers
 
-from lamin_cli._cache import cache
 from lamin_cli._io import io
 from lamin_cli._migration import migrate
 from lamin_cli._settings import settings
@@ -146,7 +143,7 @@ def login(user: str, key: str | None):
 
     After authenticating once, you can re-authenticate and switch between accounts via `lamin login myhandle`.
 
-    See also: Login in a Python session via {func}`~lamindb.setup.login`.
+    → Python/R alternative: {func}`~lamindb.setup.login`
     """
     return login_(user, key=key)
 
@@ -181,9 +178,19 @@ def init(
     db: str | None,
     modules: str | None,
 ):
-    """Init a LaminDB instance.
+    """Initialize an instance.
 
-    See also: Init in a Python session via {func}`~lamindb.setup.init`.
+    This initializes a LaminDB instance, for example:
+
+    ```
+    lamin init --storage ./mydata
+    lamin init --storage s3://my-bucket
+    lamin init --storage gs://my-bucket
+    lamin init --storage ./mydata --modules bionty
+    lamin init --storage ./mydata --modules bionty,pertdb
+    ```
+
+    → Python/R alternative: {func}`~lamindb.setup.init`
     """
     return init_(storage=storage, db=db, modules=modules, name=name)
 
@@ -191,73 +198,108 @@ def init(
 # fmt: off
 @main.command()
 @click.argument("instance", type=str)
-@click.option("--use_proxy_db", is_flag=True, help="Use proxy database connection.")
 # fmt: on
-def connect(instance: str, use_proxy_db: bool):
-    """Configure default instance for connections.
+def connect(instance: str):
+    """Set a default instance for auto-connection.
 
-    Python/R sessions and CLI commands will then auto-connect to the configured instance.
+    Python/R sessions and CLI commands will then auto-connect to this LaminDB instance.
 
-    Pass a slug (`account/name`) or URL (`https://lamin.ai/account/name`).
+    Pass a slug (`account/name`) or URL (`https://lamin.ai/account/name`), for example:
+
+    ```
+    lamin connect laminlabs/cellxgene
+    lamin connect https://lamin.ai/laminlabs/cellxgene
+    ```
 
-    See also: Connect in a Python session via {func}`~lamindb.connect`.
+    → Python/R alternative: {func}`~lamindb.connect` the global default database or a database object via {class}`~lamindb.DB`
     """
-    return connect_(instance, use_proxy_db=use_proxy_db)
+    return connect_(instance)
 
 
 @main.command()
 def disconnect():
-    """Clear default instance configuration.
+    """Unset the default instance for auto-connection.
 
-    See also: Disconnect in a Python session via {func}`~lamindb.setup.disconnect`.
+    Python/R sessions and CLI commands will no longer auto-connect to a LaminDB instance.
+
+    For example:
+
+    ```
+    lamin disconnect
+    ```
+
+    → Python/R alternative: {func}`~lamindb.setup.disconnect`
     """
     return disconnect_()
 
 
 # fmt: off
 @main.command()
-@click.argument("entity", type=str)
-@click.option("--name", type=str, default=None, help="A name.")
+@click.argument("registry", type=click.Choice(["branch", "project"]))
+@click.argument("name", type=str, required=False)
+# below is deprecated, for backward compatibility
+@click.option("--name", "name_opt", type=str, default=None, hidden=True, help="A name.")
 # fmt: on
-def create(entity: Literal["branch"], name: str | None = None):
-    """Create a record for an entity.
+def create(
+    registry: Literal["branch", "project"],
+    name: str | None,
+    name_opt: str | None,
+):
+    """Create an object.
 
     Currently only supports creating branches and projects.
 
     ```
-    lamin create branch --name my_branch
-    lamin create project --name my_project
+    lamin create branch my_branch
+    lamin create project my_project
     ```
+
+    → Python/R alternative: {class}`~lamindb.Branch` and {class}`~lamindb.Project`.
     """
+    resolved_name = name if name is not None else name_opt
+    if resolved_name is None:
+        raise click.UsageError(
+            "Specify a name. Examples: lamin create branch my_branch, lamin create project my_project"
+        )
+    if name_opt is not None:
+        warnings.warn(
+            "lamin create --name is deprecated; use 'lamin create <registry> <name>' instead, e.g. lamin create branch my_branch.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     from lamindb.models import Branch, Project
 
-    if entity == "branch":
-        record = Branch(name=name).save()
-    elif entity == "project":
-        record = Project(name=name).save()
+    if registry == "branch":
+        record = Branch(name=resolved_name).save()
+    elif registry == "project":
+        record = Project(name=resolved_name).save()
     else:
-        raise NotImplementedError(f"Creating {entity} is not implemented.")
-    logger.important(f"created {entity}: {record.name}")
+        raise NotImplementedError(f"Creating {registry} object is not implemented.")
+    logger.important(f"created {registry}: {record.name}")
 
 
 # fmt: off
 @main.command(name="list")
-@click.argument("entity", type=str)
-@click.option("--name", type=str, default=None, help="A name.")
+@click.argument("registry", type=str)
 # fmt: on
-def list_(entity: Literal["branch"], name: str | None = None):
-    """List records for an entity.
+def list_(registry: Literal["branch", "space"]):
+    """List objects.
+
+    For example:
 
     ```
     lamin list branch
     lamin list space
     ```
+
+    → Python/R alternative: {method}`~lamindb.Branch.to_dataframe()`
     """
-    assert entity in {"branch", "space"}, "Currently only supports listing branches and spaces."
+    assert registry in {"branch", "space"}, "Currently only supports listing branches and spaces."
 
     from lamindb.models import Branch, Space
 
-    if entity == "branch":
+    if registry == "branch":
         print(Branch.to_dataframe())
     else:
         print(Space.to_dataframe())
@@ -265,28 +307,56 @@ def list_(entity: Literal["branch"], name: str | None = None):
 
 # fmt: off
 @main.command()
-@click.option("--branch", type=str, default=None, help="A valid branch name or uid.")
-@click.option("--space", type=str, default=None, help="A valid branch name or uid.")
+@click.argument("registry", type=click.Choice(["branch", "space"]), required=False)
+@click.argument("name", type=str, required=False)
+# below are deprecated, for backward compatibility
+@click.option("--branch", type=str, default=None, hidden=True, help="A valid branch name or uid.")
+@click.option("--space", type=str, default=None, hidden=True, help="A valid space name or uid.")
 # fmt: on
-def switch(branch: str | None = None, space: str | None = None):
+def switch(
+    registry: Literal["branch", "space"] | None,
+    name: str | None,
+    branch: str | None,
+    space: str | None,
+):
     """Switch between branches or spaces.
 
+    Python/R sessions and CLI commands will use the current default branch or space, for example:
+
     ```
-    lamin switch --branch my_branch
-    lamin switch --space our_space
+    lamin switch branch my_branch
+    lamin switch space our_space
     ```
+
+    → Python/R alternative: {attr}`~lamindb.setup.core.SetupSettings.branch` and {attr}`~lamindb.setup.core.SetupSettings.space`
     """
+    if registry is not None and name is not None:
+        branch = name if registry == "branch" else None
+        space = name if registry == "space" else None
+    elif branch is None and space is None:
+        raise click.UsageError(
+            "Specify branch or space. Examples: lamin switch branch my_branch, lamin switch space our_space"
+        )
+    else:
+        warnings.warn(
+            "lamin switch --branch and --space are deprecated; use 'lamin switch branch <name>' or 'lamin switch space <name>' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     from lamindb.setup import switch as switch_
 
     switch_(branch=branch, space=space)
 
 
 @main.command()
-@click.option("--schema", is_flag=True, help="View database schema.")
+@click.option("--schema", is_flag=True, help="View database schema via Django plugin.")
 def info(schema: bool):
-    """Show info about the environment, instance, branch, space, and user.
+    """Show info about the instance, development & cache directories, branch, space, and user.
 
-    See also: Print the instance settings in a Python session via {func}`~lamindb.setup.settings`.
+    Manage settings via [lamin settings](https://docs.lamin.ai/cli#settings).
+
+    → Python/R alternative: {func}`~lamindb.setup.settings`
     """
     if schema:
         from lamindb_setup._schema import view
@@ -301,31 +371,42 @@ def info(schema: bool):
 
 # fmt: off
 @main.command()
+# entity can be a registry or an object in the registry
 @click.argument("entity", type=str)
 @click.option("--name", type=str, default=None)
 @click.option("--uid", type=str, default=None)
-@click.option("--slug", type=str, default=None)
+@click.option("--key", type=str, default=None, help="The key for the entity (artifact, transform).")
 @click.option("--permanent", is_flag=True, default=None, help="Permanently delete the entity where applicable, e.g., for artifact, transform, collection.")
 @click.option("--force", is_flag=True, default=False, help="Do not ask for confirmation (only relevant for instance).")
 # fmt: on
-def delete(entity: str, name: str | None = None, uid: str | None = None, slug: str | None = None, permanent: bool | None = None, force: bool = False):
-    """Delete an entity.
+def delete(entity: str, name: str | None = None, uid: str | None = None, key: str | None = None, slug: str | None = None, permanent: bool | None = None, force: bool = False):
+    """Delete an object.
 
     Currently supported: `branch`, `artifact`, `transform`, `collection`, and `instance`. For example:
 
     ```
-    lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5
-    lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5 --permanent
+    # via --key or --name
+    lamin delete artifact --key mydatasets/mytable.parquet
+    lamin delete transform --key myanalyses/analysis.ipynb
     lamin delete branch --name my_branch
     lamin delete instance --slug account/name
+    # via registry and --uid
+    lamin delete artifact --uid e2G7k9EVul4JbfsE
+    lamin delete transform --uid Vul4JbfsEYAy5
+    # via URL
+    lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5
+    lamin delete https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsEYAy5 --permanent
     ```
+
+    → Python/R alternative: {method}`~lamindb.SQLRecord.delete` and {func}`~lamindb.setup.delete`
     """
     from lamin_cli._delete import delete as delete_
 
-    return delete_(entity=entity, name=name, uid=uid, slug=slug, permanent=permanent, force=force)
+    return delete_(entity=entity, name=name, uid=uid, key=key, permanent=permanent, force=force)
 
 
 @main.command()
+# entity can be a registry or an object in the registry
 @click.argument("entity", type=str, required=False)
 @click.option("--uid", help="The uid for the entity.")
 @click.option("--key", help="The key for the entity.")
@@ -333,23 +414,23 @@ def delete(entity: str, name: str | None = None, uid: str | None = None, slug: s
     "--with-env", is_flag=True, help="Also return the environment for a tranform."
 )
 def load(entity: str | None = None, uid: str | None = None, key: str | None = None, with_env: bool = False):
-    """Load a file or folder into the cache or working directory.
+    """Sync a file/folder into a local cache (artifacts) or development directory (transforms).
 
     Pass a URL or `--key`. For example:
 
     ```
-    lamin load https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE
+    # via key
     lamin load --key mydatasets/mytable.parquet
     lamin load --key analysis.ipynb
     lamin load --key myanalyses/analysis.ipynb --with-env
-    ```
-
-    You can also pass a uid and the entity type:
-
-    ```
+    # via registry and --uid
     lamin load artifact --uid e2G7k9EVul4JbfsE
     lamin load transform --uid Vul4JbfsEYAy5
+    # via URL
+    lamin load https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE
     ```
+
+    → Python/R alternative: {func}`~lamindb.Artifact.load`, no equivalent for transforms
     """
     from lamin_cli._load import load as load_
     if entity is not None:
@@ -381,30 +462,36 @@ def _describe(entity: str = "artifact", uid: str | None = None, key: str | None
 
 
 @main.command()
+# entity can be a registry or an object in the registry
 @click.argument("entity", type=str, default="artifact")
 @click.option("--uid", help="The uid for the entity.")
 @click.option("--key", help="The key for the entity.")
 def describe(entity: str = "artifact", uid: str | None = None, key: str | None = None):
-    """Describe an artifact.
+    """Describe an object.
 
     Examples:
 
     ```
+    # via --key
     lamin describe --key example_datasets/mini_immuno/dataset1.h5ad
+    # via registry and --uid
+    lamin describe artifact --uid e2G7k9EVul4JbfsE
+    # via URL
     lamin describe https://lamin.ai/laminlabs/lamin-site-assets/artifact/6sofuDVvTANB0f48
     ```
 
-    See also: Describe an artifact in a Python session via {func}`~lamindb.Artifact.describe`.
+    → Python/R alternative: {meth}`~lamindb.Artifact.describe`
     """
     _describe(entity=entity, uid=uid, key=key)
 
 
 @main.command()
+# entity can be a registry or an object in the registry
 @click.argument("entity", type=str, default="artifact")
 @click.option("--uid", help="The uid for the entity.")
 @click.option("--key", help="The key for the entity.")
 def get(entity: str = "artifact", uid: str | None = None, key: str | None = None):
-    """Query metadata about an entity.
+    """Query metadata about an object.
 
     Currently equivalent to `lamin describe`.
     """
@@ -420,11 +507,25 @@ def get(entity: str = "artifact", uid: str | None = None, key: str | None = None
 @click.option("--project", type=str, default=None, help="A valid project name or uid.")
 @click.option("--space", type=str, default=None, help="A valid space name or uid.")
 @click.option("--branch", type=str, default=None, help="A valid branch name or uid.")
-@click.option("--registry", type=str, default=None, help="Either 'artifact' or 'transform'. If not passed, chooses based on path suffix.")
-def save(path: str, key: str, description: str, stem_uid: str, project: str, space: str, branch: str, registry: str):
-    """Save a file or folder.
+@click.option(
+    "--registry",
+    type=click.Choice(["artifact", "transform"]),
+    default=None,
+    help="Either 'artifact' or 'transform'. If not passed, chooses based on path suffix.",
+)
+def save(
+    path: str,
+    key: str,
+    description: str,
+    stem_uid: str,
+    project: str,
+    space: str,
+    branch: str,
+    registry: Literal["artifact", "transform"] | None,
+):
+    """Save a file or folder as an artifact or transform.
 
-    Example: Given a valid project name "my_project",
+    Example:
 
     ```
     lamin save my_table.csv --key my_tables/my_table.csv --project my_project
@@ -433,9 +534,11 @@ def save(path: str, key: str, description: str, stem_uid: str, project: str, spa
     By passing a `--project` identifier, the artifact will be labeled with the corresponding project.
     If you pass a `--space` or `--branch` identifier, you save the artifact in the corresponding {class}`~lamindb.Space` or on the corresponding {class}`~lamindb.Branch`.
 
-    Note: Defaults to saving `.py`, `.ipynb`, `.R`, `.Rmd`, and `.qmd` as {class}`~lamindb.Transform` and
+    Defaults to saving `.py`, `.ipynb`, `.R`, `.Rmd`, and `.qmd` as {class}`~lamindb.Transform` and
     other file types and folders as {class}`~lamindb.Artifact`. You can enforce saving a file as
     an {class}`~lamindb.Artifact` by passing `--registry artifact`.
+
+    → Python/R alternative: {class}`~lamindb.Artifact` and {class}`~lamindb.Transform`
     """
     if save_(path=path, key=key, description=description, stem_uid=stem_uid, project=project, space=space, branch=branch, registry=registry) is not None:
         sys.exit(1)
@@ -461,6 +564,8 @@ def track():
     ```
     sh my_script.sh
     ```
+
+    → Python/R alternative: {func}`~lamindb.track` and {func}`~lamindb.finish` for (non-shell) scripts or notebooks
     """
     from lamin_cli._context import track as track_
     return track_()
@@ -468,61 +573,85 @@ def track():
 
 @main.command()
 def finish():
-    """Finish the current tracked run of a shell script.
+    """Finish a currently tracked run of a shell script.
 
-    This command works like {func}`~lamindb.finish()` in a Python session.
+    → Python/R alternative: {func}`~lamindb.finish()`
     """
     from lamin_cli._context import finish as finish_
     return finish_()
 
 
 @main.command()
+# entity can be a registry or an object in the registry
 @click.argument("entity", type=str, default=None, required=False)
 @click.option("--key", type=str, default=None, help="The key of an artifact or transform.")
 @click.option("--uid", type=str, default=None, help="The uid of an artifact or transform.")
 @click.option("--project", type=str, default=None, help="A valid project name or uid.")
+@click.option("--ulabel", type=str, default=None, help="A valid ulabel name or uid.")
+@click.option("--record", type=str, default=None, help="A valid record name or uid.")
 @click.option("--features", multiple=True, help="Feature annotations. Supports: feature=value, feature=val1,val2, or feature=\"val1\",\"val2\"")
-def annotate(entity: str | None, key: str, uid: str, project: str, features: tuple):
+def annotate(entity: str | None, key: str, uid: str, project: str, ulabel: str, record: str, features: tuple):
     """Annotate an artifact or transform.
 
-    Entity is either 'artifact' or 'transform'. If not passed, chooses based on key suffix.
-
-    You can annotate with projects and valid features & values. For example,
+    You can annotate with projects, ulabels, records, and valid features & values. For example,
 
     ```
+    # via --key
     lamin annotate --key raw/sample.fastq --project "My Project"
+    lamin annotate --key raw/sample.fastq --ulabel "My ULabel" --record "Experiment 1"
     lamin annotate --key raw/sample.fastq --features perturbation=IFNG,DMSO cell_line=HEK297
     lamin annotate --key my-notebook.ipynb --project "My Project"
+    # via registry and --uid
+    lamin annotate artifact --uid e2G7k9EVul4JbfsE --project "My Project"
+    # via URL
+    lamin annotate https://lamin.ai/account/instance/artifact/e2G7k9EVul4JbfsE --project "My Project"
     ```
-    """
-    import lamindb as ln
 
+    → Python/R alternative: `artifact.features.add_values()` via {meth}`~lamindb.models.FeatureManager.add_values` and `artifact.projects.add()`, `artifact.ulabels.add()`, `artifact.records.add()`, ... via {meth}`~lamindb.models.RelatedManager.add`
+    """
     from lamin_cli._annotate import _parse_features_list
     from lamin_cli._save import infer_registry_from_path
 
-    # once we enable passing the URL as entity, then we don't need to throw this error
-    if not ln.setup.settings._instance_exists:
-        raise click.ClickException("Not connected to an instance. Please run: lamin connect account/name")
-
-    if entity is None:
-        if key is not None:
-            registry = infer_registry_from_path(key)
-        else:
-            registry = "artifact"
+    # Handle URL: decompose and connect (same pattern as load/delete)
+    if entity is not None and entity.startswith("https://"):
+        url = entity
+        instance, registry, uid = decompose_url(url)
+        if registry not in {"artifact", "transform"}:
+            raise click.ClickException(
+                f"Annotate does not support {registry}. Use artifact or transform URLs."
+            )
+        ln_setup.connect(instance)
     else:
-        registry = entity
+        if not ln_setup.settings._instance_exists:
+            raise click.ClickException(
+                "Not connected to an instance. Please run: lamin connect account/name"
+            )
+        if entity is None:
+            registry = infer_registry_from_path(key) if key is not None else "artifact"
+        else:
+            registry = entity
+        if registry not in {"artifact", "transform"}:
+            raise click.ClickException(
+                f"Annotate does not support {registry}. Use artifact or transform URLs."
+            )
+
+    # import lamindb after connect went through
+    import lamindb as ln
+
     if registry == "artifact":
         model = ln.Artifact
     else:
         model = ln.Transform
 
-    # Get the artifact
+    # Get the artifact or transform
     if key is not None:
         artifact = model.get(key=key)
     elif uid is not None:
         artifact = model.get(uid)  # do not use uid=uid, because then no truncated uids would work
     else:
-        raise ln.errors.InvalidArgument("Either --key or --uid must be provided")
+        raise ln.errors.InvalidArgument(
+            "Either pass a URL as entity or provide --key or --uid"
+        )
 
     # Handle project annotation
     if project is not None:
@@ -535,6 +664,28 @@ def annotate(entity: str | None, key: str, uid: str, project: str, features: tup
             )
         artifact.projects.add(project_record)
 
+    # Handle ulabel annotation
+    if ulabel is not None:
+        ulabel_record = ln.ULabel.filter(
+            ln.Q(name=ulabel) | ln.Q(uid=ulabel)
+        ).one_or_none()
+        if ulabel_record is None:
+            raise ln.errors.InvalidArgument(
+                f"ULabel '{ulabel}' not found, either create it with `ln.ULabel(name='...').save()` or fix typos."
+            )
+        artifact.ulabels.add(ulabel_record)
+
+    # Handle record annotation
+    if record is not None:
+        record_record = ln.Record.filter(
+            ln.Q(name=record) | ln.Q(uid=record)
+        ).one_or_none()
+        if record_record is None:
+            raise ln.errors.InvalidArgument(
+                f"Record '{record}' not found, either create it with `ln.Record(name='...').save()` or fix typos."
+            )
+        artifact.records.add(record_record)
+
     # Handle feature annotations
     if features:
         feature_dict = _parse_features_list(features)
@@ -548,7 +699,7 @@ def annotate(entity: str | None, key: str, uid: str, project: str, features: tup
 @click.argument("filepath", type=str)
 @click.option("--project", type=str, default=None, help="A valid project name or uid. When running on Modal, creates an app with the same name.", required=True)
 @click.option("--image-url", type=str, default=None, help="A URL to the base docker image to use.")
-@click.option("--packages", type=str, default="lamindb", help="A comma-separated list of additional packages to install.")
+@click.option("--packages", type=str, default=None, help="A comma-separated list of additional packages to install.")
 @click.option("--cpu", type=float, default=None, help="Configuration for the CPU.")
 @click.option("--gpu", type=str, default=None, help="The type of GPU to use (only compatible with cuda images).")
 def run(filepath: str, project: str, image_url: str, packages: str, cpu: int, gpu: str | None):
@@ -561,6 +712,8 @@ def run(filepath: str, project: str, image_url: str, packages: str, cpu: int, gp
     ```
     lamin run my_script.py --project my_project
     ```
+
+    → Python/R alternative: no equivalent
     """
     from lamin_cli.compute.modal import Runner
 
@@ -589,10 +742,54 @@ def run(filepath: str, project: str, image_url: str, packages: str, cpu: int, gp
 
 
 main.add_command(settings)
-main.add_command(cache)
 main.add_command(migrate)
 main.add_command(io)
 
+
+def _deprecated_cache_set(cache_dir: str) -> None:
+    logger.warning("'lamin cache' is deprecated. Use 'lamin settings cache-dir' instead.")
+    from lamindb_setup._cache import set_cache_dir
+
+    set_cache_dir(cache_dir)
+
+
+def _deprecated_cache_clear() -> None:
+    logger.warning("'lamin cache' is deprecated. Use 'lamin settings cache-dir' instead.")
+    from lamindb_setup._cache import clear_cache_dir
+
+    clear_cache_dir()
+
+
+def _deprecated_cache_get() -> None:
+    logger.warning("'lamin cache' is deprecated. Use 'lamin settings cache-dir' instead.")
+    from lamindb_setup._cache import get_cache_dir
+
+    click.echo(f"The cache directory is {get_cache_dir()}")
+
+
+@main.group("cache", hidden=True)
+def deprecated_cache():
+    """Deprecated. Use 'lamin settings cache-dir' instead."""
+
+
+@deprecated_cache.command("set")
+@click.argument(
+    "cache_dir",
+    type=click.Path(dir_okay=True, file_okay=False),
+)
+def _deprecated_cache_set_cmd(cache_dir: str) -> None:
+    _deprecated_cache_set(cache_dir)
+
+
+@deprecated_cache.command("clear")
+def _deprecated_cache_clear_cmd() -> None:
+    _deprecated_cache_clear()
+
+
+@deprecated_cache.command("get")
+def _deprecated_cache_get_cmd() -> None:
+    _deprecated_cache_get()
+
 # https://stackoverflow.com/questions/57810659/automatically-generate-all-help-documentation-for-click-commands
 # https://claude.ai/chat/73c28487-bec3-4073-8110-50d1a2dd6b84
 def _generate_help():
@@ -601,6 +798,8 @@ def _generate_help():
     def recursive_help(
         cmd: Command, parent: Context | None = None, name: tuple[str, ...] = ()
     ):
+        if getattr(cmd, "hidden", False):
+            return
         ctx = click.Context(cmd, info_name=cmd.name, parent=parent)
         assert cmd.name
         name = (*name, cmd.name)
@@ -615,6 +814,8 @@ def _generate_help():
         }
 
         for sub in getattr(cmd, "commands", {}).values():
+            if getattr(sub, "hidden", False):
+                continue
             recursive_help(sub, ctx, name=name)
 
     recursive_help(main)

lamin_cli/_cache.py

@@ -10,7 +10,7 @@ else:
 
 @click.group()
 def cache():
-    """Manage cache."""
+    """Get, set, or clear the cache directory."""
 
 
 @cache.command("set")

lamin_cli/_delete.py

@@ -1,5 +1,7 @@
+import click
 from lamindb_setup import connect
 from lamindb_setup import delete as delete_instance
+from lamindb_setup.errors import StorageNotEmpty
 
 from .urls import decompose_url
 
@@ -8,7 +10,7 @@ def delete(
     entity: str,
     name: str | None = None,
     uid: str | None = None,
-    slug: str | None = None,
+    key: str | None = None,
     permanent: bool | None = None,
     force: bool = False,
 ):
@@ -24,21 +26,60 @@ def delete(
 
         Branch.get(name=name).delete(permanent=permanent)
     elif entity == "artifact":
-        assert uid is not None, "You have to pass a uid for deleting an artifact."
+        assert uid is not None or key is not None, (
+            "You have to pass a uid or key for deleting an artifact."
+        )
         from lamindb import Artifact
 
-        Artifact.get(uid).delete(permanent=permanent)
+        if key is not None:
+            record = Artifact.objects.filter(key=key).order_by("-created_at").first()
+            if record is None:
+                raise SystemExit(f"Artifact with key={key} does not exist.")
+        else:
+            record = Artifact.get(uid)
+        record.delete(permanent=permanent)
     elif entity == "transform":
-        assert uid is not None, "You have to pass a uid for deleting an transform."
+        assert uid is not None or key is not None, (
+            "You have to pass a uid or key for deleting a transform."
+        )
         from lamindb import Transform
 
-        Transform.get(uid).delete(permanent=permanent)
+        if key is not None:
+            record = Transform.objects.filter(key=key).order_by("-created_at").first()
+            if record is None:
+                raise SystemExit(f"Transform with key={key} does not exist.")
+        else:
+            record = Transform.get(uid)
+        record.delete(permanent=permanent)
     elif entity == "collection":
-        assert uid is not None, "You have to pass a uid for deleting an collection."
+        assert uid is not None or key is not None, (
+            "You have to pass a uid or key for deleting a collection."
+        )
         from lamindb import Collection
 
-        Collection.get(uid).delete(permanent=permanent)
-    elif entity == "instance":
-        return delete_instance(slug, force=force)
-    else:  # backwards compatibility
-        return delete_instance(entity, force=force)
+        if key is not None:
+            record = Collection.objects.filter(key=key).order_by("-created_at").first()
+            if record is None:
+                raise SystemExit(f"Collection with key={key} does not exist.")
+        else:
+            record = Collection.get(uid)
+        record.delete(permanent=permanent)
+    elif entity == "record":
+        assert uid is not None or name is not None, (
+            "You have to pass a uid or name for deleting a record."
+        )
+        from lamindb import Record
+
+        if name is not None:
+            record = Record.objects.get(name=name)
+            if record is None:
+                raise SystemExit(f"Record with name={name} does not exist.")
+        else:
+            record = Record.get(uid)
+        record.delete(permanent=permanent)
+    else:
+        # could introduce "db" as an entity
+        try:
+            return delete_instance(entity, force=force)
+        except StorageNotEmpty as e:
+            raise click.ClickException(str(e)) from e

lamin_cli/_io.py

@@ -31,6 +31,7 @@ def io():
 # fmt: on
 def snapshot(upload: bool, track: bool) -> None:
     """Create a SQLite snapshot of the connected instance."""
+    from lamindb_setup.io import export_db
     if not ln_setup.settings._instance_exists:
         raise click.ClickException(
             "Not connected to an instance. Please run: lamin connect account/name"
@@ -52,8 +53,8 @@ def snapshot(upload: bool, track: bool) -> None:
 
     with tempfile.TemporaryDirectory() as export_dir:
         if track:
-            ln.track()
-        ln_setup.io.export_db(module_names=modules_complete, output_dir=export_dir)
+            ln.track("o39ljgTzvFew", key="__lamin_io_snapshot__.py")
+        export_db(module_names=modules_complete, output_dir=export_dir)
         if track:
             ln.finish()
 
@@ -109,13 +110,14 @@ def snapshot(upload: bool, track: bool) -> None:
 # fmt: on
 def exportdb(modules: str | None, output_dir: str, max_workers: int, chunk_size: int):
     """Export registry tables to parquet files."""
+    from lamindb_setup.io import export_db
     if not ln_setup.settings._instance_exists:
         raise click.ClickException(
             "Not connected to an instance. Please run: lamin connect account/name"
         )
 
     module_list = modules.split(",") if modules else None
-    ln_setup.io.export_db(
+    export_db(
         module_names=module_list,
         output_dir=output_dir,
         max_workers=max_workers,
@@ -131,13 +133,14 @@ def exportdb(modules: str | None, output_dir: str, max_workers: int, chunk_size:
 # fmt: on
 def importdb(modules: str | None, input_dir: str, if_exists: str):
     """Import registry tables from parquet files."""
+    from lamindb_setup.io import import_db
     if not ln_setup.settings._instance_exists:
         raise click.ClickException(
             "Not connected to an instance. Please run: lamin connect account/name"
         )
 
     module_list = modules.split(",") if modules else None
-    ln_setup.io.import_db(
+    import_db(
         module_names=module_list,
         input_dir=input_dir,
         if_exists=if_exists,

lamin_cli/_save.py

@@ -51,7 +51,7 @@ def parse_uid_from_code(content: str, suffix: str) -> str | None:
     elif suffix == ".sh":
         return None
     else:
-        raise SystemExit(
+        raise click.ClickException(
             "Only .py, .ipynb, .R, .qmd, .Rmd, .sh files are supported for saving"
             " transforms."
         )
@@ -113,14 +113,14 @@ def save(
             ln.Q(name=project) | ln.Q(uid=project)
         ).one_or_none()
         if project_record is None:
-            raise ln.errors.InvalidArgument(
+            raise click.ClickException(
                 f"Project '{project}' not found, either create it with `ln.Project(name='...').save()` or fix typos."
             )
     space_record = None
     if space is not None:
         space_record = ln.Space.filter(ln.Q(name=space) | ln.Q(uid=space)).one_or_none()
         if space_record is None:
-            raise ln.errors.InvalidArgument(
+            raise click.ClickException(
                 f"Space '{space}' not found, either create it on LaminHub or fix typos."
             )
     branch_record = None
@@ -129,7 +129,7 @@ def save(
             ln.Q(name=branch) | ln.Q(uid=branch)
         ).one_or_none()
         if branch_record is None:
-            raise ln.errors.InvalidArgument(
+            raise click.ClickException(
                 f"Branch '{branch}' not found, either create it with `ln.Branch(name='...').save()` or fix typos."
             )
 
@@ -145,7 +145,7 @@ def save(
                 .first()
             )
             if revises is None:
-                raise ln.errors.InvalidArgument("The stem uid is not found.")
+                raise click.ClickException("The stem uid is not found.")
 
         if is_cloud_path:
             if key is not None:
@@ -266,7 +266,30 @@ def save(
                 .first()
             )
             if revises is None:
-                raise ln.errors.InvalidArgument("The stem uid is not found.")
+                # check if the transform is on other branches
+                revises_other_branches = (
+                    ln.Transform.filter(uid__startswith=stem_uid, branch=None)
+                    .order_by("-created_at")
+                    .first()
+                )
+                if revises_other_branches is not None:
+                    if revises_other_branches.branch_id == -1:
+                        raise click.ClickException(
+                            "Transform is in the trash, please restore it before running `lamin save`!"
+                        )
+                    elif revises_other_branches.branch_id == 0:
+                        raise click.ClickException(
+                            "Transform is in the archive, please restore it before running `lamin save`!"
+                        )
+                    elif (
+                        revises_other_branches.branch_id != ln_setup.settings.branch.id
+                    ):
+                        raise click.ClickException(
+                            "Transform is on a different branch"
+                            f"({revises_other_branches.branch.name}), please switch to the correct branch"
+                            " before running `lamin save`!"
+                        )
+                raise click.ClickException("The stem uid is not found.")
         if transform is None:
             if ppath.suffix == ".ipynb":
                 from nbproject.dev import read_notebook
@@ -322,4 +345,6 @@ def save(
         )
         return return_code
     else:
-        raise SystemExit("Allowed values for '--registry' are: 'artifact', 'transform'")
+        raise click.ClickException(
+            "Allowed values for '--registry' are: 'artifact', 'transform'"
+        )

lamin_cli/_settings.py

@@ -12,35 +12,38 @@ else:
 @click.group(invoke_without_command=True)
 @click.pass_context
 def settings(ctx):
-    """Manage settings.
+    """Manage development & cache directories, branch, and space settings.
 
-    Call without subcommands and options to show settings:
+    Get or set a setting by name:
 
-    ```
-    lamin settings
-    ```
+    - `dev-dir` → development directory {attr}`~lamindb.setup.core.SetupSettings.dev_dir`
+    - `cache-dir` → cache directory {attr}`~lamindb.setup.core.SetupSettings.cache_dir`
+    - `branch` → branch {attr}`~lamindb.setup.core.SetupSettings.branch`
+    - `space` → space {attr}`~lamindb.setup.core.SetupSettings.space`
 
-    Allows to get and set these settings:
+    Display via [lamin info](https://docs.lamin.ai/cli#info)
 
-    - `dev-dir` → {attr}`~lamindb.setup.core.SetupSettings.dev_dir`
-    - `private-django-api` → {attr}`~lamindb.setup.core.SetupSettings.private_django_api`
-    - `branch` → current branch (use `lamin switch --branch` to change)
-    - `space` → current space (use `lamin switch --space` to change)
-
-    Examples for getting a setting:
+    Examples:
 
     ```
-    lamin settings get dev-dir
-    lamin settings get branch
+    # dev-dir
+    lamin settings dev-dir get
+    lamin settings dev-dir set .  # set to current directory
+    lamin settings dev-dir set ~/my-project
+    lamin settings dev-dir unset
+    # cache-dir
+    lamin settings cache-dir get
+    lamin settings cache-dir set /path/to/cache
+    lamin settings cache-dir clear
+    # branch
+    lamin settings branch get
+    lamin settings branch set main
+    # space
+    lamin settings space get
+    lamin settings space set all
     ```
 
-    Examples for setting the working directory:
-
-    ```
-    lamin settings set dev-dir .  # set dev-dir to current directory
-    lamin settings set dev-dir ~/my-project  # set dev-dir to ~/my-project
-    lamin settings set dev-dir none  # unset dev-dir
-    ```
+    → Python/R alternative: {attr}`~lamindb.setup.core.SetupSettings.dev_dir`, {attr}`~lamindb.setup.core.SetupSettings.cache_dir`, {attr}`~lamindb.setup.core.SetupSettings.branch`, and {attr}`~lamindb.setup.core.SetupSettings.space`
     """
     if ctx.invoked_subcommand is None:
         from lamindb_setup import settings as settings_
@@ -49,7 +52,53 @@ def settings(ctx):
         click.echo(settings_)
 
 
-@settings.command("set")
+# -----------------------------------------------------------------------------
+# dev-dir group (pattern: lamin settings dev-dir get/set)
+# -----------------------------------------------------------------------------
+
+
+@click.group("dev-dir")
+def dev_dir_group():
+    """Get or set the development directory."""
+
+
+@dev_dir_group.command("get")
+def dev_dir_get():
+    """Show the current development directory."""
+    from lamindb_setup import settings as settings_
+
+    value = settings_.dev_dir
+    click.echo(value if value is not None else "None")
+
+
+@dev_dir_group.command("set")
+@click.argument("value", type=str)
+def dev_dir_set(value: str):
+    """Set the development directory."""
+    from lamindb_setup import settings as settings_
+
+    if value.lower() == "none":
+        value = None  # type: ignore[assignment]
+    settings_.dev_dir = value
+
+
+@dev_dir_group.command("unset")
+def dev_dir_unset():
+    """Unset the development directory."""
+    from lamindb_setup import settings as settings_
+
+    settings_.dev_dir = None
+
+
+settings.add_command(dev_dir_group)
+
+
+# -----------------------------------------------------------------------------
+# Legacy get/set (hidden, backward compatibility)
+# -----------------------------------------------------------------------------
+
+
+@settings.command("set", hidden=True)
 @click.argument(
     "setting",
     type=click.Choice(
@@ -57,8 +106,8 @@ def settings(ctx):
     ),
 )
 @click.argument("value")  # No explicit type - let Click handle it
-def set(setting: str, value: str):
-    """Set a setting."""
+def set_legacy(setting: str, value: str):
+    """Set a setting (legacy). Use lamin settings <name> set <value> instead."""
     from lamindb_setup import settings as settings_
 
     if setting == "auto-connect":
@@ -71,7 +120,7 @@ def set(setting: str, value: str):
         settings_.dev_dir = value
 
 
-@settings.command("get")
+@settings.command("get", hidden=True)
 @click.argument(
     "setting",
     type=click.Choice(
@@ -79,8 +128,8 @@ def set(setting: str, value: str):
         case_sensitive=False,
     ),
 )
-def get(setting: str):
-    """Get a setting."""
+def get_legacy(setting: str):
+    """Get a setting (legacy). Use lamin settings <name> get instead."""
     from lamindb_setup import settings as settings_
 
     if setting == "branch":
@@ -94,3 +143,12 @@ def get(setting: str):
     else:
         value = getattr(settings_, setting.replace("-", "_"))
     click.echo(value)
+
+
+# -----------------------------------------------------------------------------
+# cache-dir (already uses lamin settings cache-dir get/set/clear)
+# -----------------------------------------------------------------------------
+
+from lamin_cli._cache import cache
+
+settings.add_command(cache, "cache-dir")

lamin_cli/clone/create_sqlite_clone_and_import_db.py

@@ -6,6 +6,8 @@ from pathlib import Path
 import lamindb_setup as ln_setup
 
 if __name__ == "__main__":
+    from lamindb_setup.io import import_db
+
     sys.path.insert(0, str(Path(__file__).parent.parent))
 
     parser = argparse.ArgumentParser()
@@ -25,7 +27,7 @@ if __name__ == "__main__":
         storage=f"{instance_name}-clone", modules=f"{','.join(modules_without_lamindb)}"
     )
 
-    ln_setup.io.import_db(
+    import_db(
         module_names=list(modules_complete), input_dir=export_dir, if_exists="replace"
     )
 

lamin_cli/compute/modal.py

@@ -157,11 +157,11 @@ class Runner:
     ) -> modal.Image:
         if env_variables is None:
             env_variables = {}
+        base_packages = ["lamindb", "httpx_retries"]
         if packages is None:
-            packages = ["lamindb"]
+            packages = base_packages
         else:
-            packages.append("lamindb")  # Append lamindb to the list of packages
-
+            packages += base_packages
         if image_url is None:
             image = modal.Image.debian_slim(python_version=python_version)
         else:
@@ -170,6 +170,5 @@ class Runner:
             image.pip_install(packages)
             .env(env_variables)
             .add_local_python_source("lamindb", "lamindb_setup", copy=True)
-            .run_commands("lamin settings set auto-connect true")
             .add_local_dir(local_dir, remote_dir)
         )

lamin_cli/urls.py

@@ -1,6 +1,8 @@
 def decompose_url(url: str) -> tuple[str, str, str]:
-    assert any(keyword in url for keyword in ["transform", "artifact", "collection"])
-    for entity in ["transform", "artifact", "collection"]:
+    assert any(
+        keyword in url for keyword in ["transform", "artifact", "collection", "record"]
+    )
+    for entity in ["transform", "artifact", "collection", "record"]:
         if entity in url:
             break
     uid = url.split(f"{entity}/")[1]

{lamin_cli-1.11.0.dist-info → lamin_cli-1.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lamin_cli
-Version: 1.11.0
+Version: 1.12.0
 Summary: Lamin CLI.
 Author-email: Lamin Labs <open-source@lamin.ai>
 Description-Content-Type: text/markdown

lamin_cli-1.12.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+lamin_cli/__init__.py,sha256=IJ_B3QJrPMYc1SfgQQ1WgVnE2dEZOf8wSmQIGZhAauw,605
+lamin_cli/__main__.py,sha256=HkZh79zC2mrdmAtpib1uE83T_E5pRUuYrYXqgfrmY8w,27931
+lamin_cli/_annotate.py,sha256=ZD76__K-mQt7UpYqyM1I2lKCs-DraTmnkjsByIHmD-g,1839
+lamin_cli/_cache.py,sha256=SvfgC0pIpsjIGUYm21oPUfE_RCOG2_b0cvDscLtzbYo,826
+lamin_cli/_context.py,sha256=JLhv98isasX_M_o6tIDkeBWcNH8ryRrl3nk2rmwsuD4,2392
+lamin_cli/_delete.py,sha256=TQV-CJOV3tYBGm6vCj0JKymptrXWhBvJ8CZPfDVyzAw,3061
+lamin_cli/_io.py,sha256=HPFpASrTa3zLsIXmTpZ69l34t3ZoYIa_SNHOclJnd-o,5175
+lamin_cli/_load.py,sha256=v7PCB7sYqGs6jF186aN191lTV2Mr5jdayHKSmdgsw_k,8445
+lamin_cli/_migration.py,sha256=w-TLYC2q6sqcfNtIUewqRW_69_xy_71X3eSV7Ud58jk,1239
+lamin_cli/_save.py,sha256=PiBFlTgPMPdFg4eMqRPYOiF4rl7R6LA3e3RTpZc_gaM,13806
+lamin_cli/_settings.py,sha256=vuKZeEToEh0pb_R4ECzWpe6FeJgmIACLEupPYxQ60k4,4781
+lamin_cli/urls.py,sha256=6yTBFByrzdWIntFjupC5Dt8hYkl4agR31D4g1zjzPK8,401
+lamin_cli/clone/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lamin_cli/clone/_clone_verification.py,sha256=8hRFZt_1Z0i2wMqKBkrioq01RJEjwHy9cYmw6LV4PXI,1835
+lamin_cli/clone/create_sqlite_clone_and_import_db.py,sha256=m4Lzm1UvqNjYR2WKE0u_g-RrKv77pdVwHyFOKdR0exQ,1576
+lamin_cli/compute/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lamin_cli/compute/modal.py,sha256=-QBnqxjI8AJDjkF7-Q30o4m3EpSeJ2_n5wYxedaPiLA,5955
+lamin_cli-1.12.0.dist-info/entry_points.txt,sha256=Qms85i9cZPlu-U7RnVZhFsF7vJ9gaLZUFkCjcGcXTpg,49
+lamin_cli-1.12.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+lamin_cli-1.12.0.dist-info/WHEEL,sha256=ssQ84EZ5gH1pCOujd3iW7HClo_O_aDaClUbX4B8bjKY,100
+lamin_cli-1.12.0.dist-info/METADATA,sha256=JN15Pvzdjb2Eshdqrp5lh6NM-kkmccfy-STokqEFNGY,338
+lamin_cli-1.12.0.dist-info/RECORD,,

lamin_cli-1.11.0.dist-info/RECORD

@@ -1,22 +0,0 @@
-lamin_cli/__init__.py,sha256=bd6la8_wxlClB7o8h3FNAjQ6z8HPcZ4QqxvVp4Cvycg,605
-lamin_cli/__main__.py,sha256=DEifHuxyyffXHVpBjn9-LVpVUsuSnRhicxTfsuZ0YUw,20791
-lamin_cli/_annotate.py,sha256=ZD76__K-mQt7UpYqyM1I2lKCs-DraTmnkjsByIHmD-g,1839
-lamin_cli/_cache.py,sha256=oplwE8AcS_9PYptQUZxff2qTIdNFS81clGPkJNWk098,800
-lamin_cli/_context.py,sha256=JLhv98isasX_M_o6tIDkeBWcNH8ryRrl3nk2rmwsuD4,2392
-lamin_cli/_delete.py,sha256=1wp8LQdiWHJznRrm4abxEhApB9derBWEm25ufrzjvIg,1531
-lamin_cli/_io.py,sha256=DboDoecZN5OLCHe5vJzOLuwztW8hxbdRffWj1kmJ9WI,5036
-lamin_cli/_load.py,sha256=v7PCB7sYqGs6jF186aN191lTV2Mr5jdayHKSmdgsw_k,8445
-lamin_cli/_migration.py,sha256=w-TLYC2q6sqcfNtIUewqRW_69_xy_71X3eSV7Ud58jk,1239
-lamin_cli/_save.py,sha256=8dM4blz6caKJtbqND-6xJXUMlGIvo2FwvSu1CDcBPig,12517
-lamin_cli/_settings.py,sha256=nqVM8FO9kjL0SXYqP8x-Xfww6Qth4I86HKKeTirsgc4,2657
-lamin_cli/urls.py,sha256=gc72s4SpaAQA8J50CtCIWlr49DWOSL_a6OM9lXfPouM,367
-lamin_cli/clone/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lamin_cli/clone/_clone_verification.py,sha256=8hRFZt_1Z0i2wMqKBkrioq01RJEjwHy9cYmw6LV4PXI,1835
-lamin_cli/clone/create_sqlite_clone_and_import_db.py,sha256=yv2mLkHdRUao_IkZO_4Swu5w4Nieh1gMrBwPbyn4c1o,1544
-lamin_cli/compute/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lamin_cli/compute/modal.py,sha256=QnR7GyyvWWWkLnou95HxS9xxSQfw1k-SiefM_qRVnU0,6010
-lamin_cli-1.11.0.dist-info/entry_points.txt,sha256=Qms85i9cZPlu-U7RnVZhFsF7vJ9gaLZUFkCjcGcXTpg,49
-lamin_cli-1.11.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-lamin_cli-1.11.0.dist-info/WHEEL,sha256=ssQ84EZ5gH1pCOujd3iW7HClo_O_aDaClUbX4B8bjKY,100
-lamin_cli-1.11.0.dist-info/METADATA,sha256=4TK6hWuABuBxr1PYF_iBpm7KP8xNH7g4LjMWUkHgDKE,338
-lamin_cli-1.11.0.dist-info/RECORD,,