lamin_cli 1.10.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.10.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

@@ -42,6 +42,10 @@ COMMAND_GROUPS = {
             "name": "Load, save, create & delete data",
             "commands": ["load", "save", "create", "delete"],
         },
+        {
+            "name": "Tracking within shell scripts",
+            "commands": ["track", "finish"],
+        },
         {
             "name": "Describe, annotate & list data",
             "commands": ["describe", "annotate", "list"],
@@ -49,9 +53,7 @@ COMMAND_GROUPS = {
         {
             "name": "Configure",
             "commands": [
-                "checkout",
                 "switch",
-                "cache",
                 "settings",
                 "migrate",
             ],
@@ -108,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
@@ -142,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)
 
@@ -177,9 +178,19 @@ def init(
     db: str | None,
     modules: str | None,
 ):
-    """Init a LaminDB instance.
+    """Initialize an instance.
+
+    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
+    ```
 
-    See also: Init in a Python session via {func}`~lamindb.setup.init`.
+    → Python/R alternative: {func}`~lamindb.setup.init`
     """
     return init_(storage=storage, db=db, modules=modules, name=name)
 
@@ -187,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:
 
-    See also: Connect in a Python session via {func}`~lamindb.connect`.
+    ```
+    lamin connect laminlabs/cellxgene
+    lamin connect https://lamin.ai/laminlabs/cellxgene
+    ```
+
+    → 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.
+
+    Python/R sessions and CLI commands will no longer auto-connect to a LaminDB instance.
 
-    See also: Disconnect in a Python session via {func}`~lamindb.setup.disconnect`.
+    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())
@@ -261,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
@@ -297,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.")
@@ -329,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:
@@ -377,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`.
     """
@@ -416,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
@@ -429,61 +534,124 @@ 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)
 
+@main.command()
+def track():
+    """Start tracking a run of a shell script.
+
+    This command works like {func}`~lamindb.track()` in a Python session. Here is an example script:
+
+    ```
+    # my_script.sh
+    set -e         # exit on error
+    lamin track    # initiate a tracked shell script run
+    lamin load --key raw/file1.txt
+    # do something
+    lamin save processed_file1.txt --key processed/file1.txt
+    lamin finish   # mark the shell script run as finished
+    ```
+
+    If you run that script, it will track the run of the script, and save the input and output artifacts:
+
+    ```
+    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_()
+
 
 @main.command()
+def finish():
+    """Finish a currently tracked run of a shell script.
+
+    → 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:
@@ -496,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)
@@ -509,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):
@@ -522,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
 
@@ -550,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():
@@ -562,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)
@@ -576,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)