Deprecate most CLI commands

.github/workflows/test_setup.yml

@@ -50,10 +50,10 @@ jobs:
         run: |
           source .venv/bin/activate
           LIGHTLY_SERVER_LOCATION="localhost:-1"
-          lightly-crop --help
-          lightly-train --help
-          lightly-embed --help
-          lightly-magic --help
+          lightly-crop-deprecated --help
+          lightly-train-deprecated --help
+          lightly-embed-deprecated --help
+          lightly-magic-deprecated --help
           lightly-download --help
           lightly-version
       - name: Test CLI on Dataset
@@ -62,5 +62,5 @@ jobs:
           LIGHTLY_SERVER_LOCATION="localhost:-1"
           git clone https://github.com/alexeygrigorev/clothing-dataset-small clothing_dataset_small
           INPUT_DIR_1="clothing_dataset_small/test/dress"
-          lightly-train input_dir=$INPUT_DIR_1 trainer.max_epochs=1 loader.num_workers=6
-          lightly-embed input_dir=$INPUT_DIR_1
+          lightly-train-deprecated input_dir=$INPUT_DIR_1 trainer.max_epochs=1 loader.num_workers=6
+          lightly-embed-deprecated input_dir=$INPUT_DIR_1

docs/source/getting_started/command_line_tool.rst

@@ -7,6 +7,22 @@ The Lightly\ **SSL** framework provides you with a command-line interface (CLI)
 self-supervised models and create embeddings without having to write a single 
 line of code.
 
+.. warning::
+
+    Most commands of the CLI are deprecated since version 1.6.
+
+    The following commands were renamed in version 1.6 and will be removed in version
+    1.7:
+    - `lightly-crop` -> `lightly-crop-deprecated`
+    - `lightly-train` -> `lightly-train-deprecated`
+    - `lightly-embed` -> `lightly-embed-deprecated`
+    - `lightly-magic` -> `lightly-magic-deprecated`
+
+    If you would like to continue using these commands, please create an issue on the
+    :ref:`issue tracker <https://github.com/lightly-ai/lightly/issues>`_ or contact us
+    at [email protected]
+
+
 You can also have a look at this video to get an overview of how to work with 
 the CLI.
 
@@ -41,6 +57,13 @@ If Lightly\ **SSL** was installed correctly, you should see something like this:
 
 Crop Images using Labels or Predictions
 ---------------------------------------------------
+
+.. warning::
+
+    This functionality is deprecated since version 1.6. The `lightly-crop` command
+    was renamed to `lightly-crop-deprecated` in version 1.6 and will be completely
+    removed in version 1.7.
+
 For some tasks, self-supervised learning on an image level has disadvantages. For 
 example, when training an object detection model we care about local features
 describing the objects rather than features describing the full image.
@@ -49,17 +72,17 @@ One simple trick to overcome this limitation, is to use labels or to use a pre-t
 to get bounding boxes around the objects and then cropping the objects out of the
 image.
 
-We can do this using the **lightly-crop** CLI command. The CLI command crops 
+We can do this using the **lightly-crop-deprecated** CLI command. The CLI command crops 
 objects out of the input images based on labels and copies them into an output folder.
 The new folder consists now of the cropped images.
 
 .. code-block:: bash
 
     # Crop images and set the crop to be 20% around the bounding box
-    lightly-crop input_dir=images label_dir=labels output_dir=cropped_images crop_padding=0.2
+    lightly-crop-deprecated input_dir=images label_dir=labels output_dir=cropped_images crop_padding=0.2
 
     # Crop images and use the class names in the filename
-    lightly-crop input_dir=images label_dir=labels output_dir=cropped_images \
+    lightly-crop-deprecated input_dir=images label_dir=labels output_dir=cropped_images \
                  label_names_file=data.yaml
 
 The labels should be in the yolo format. For each image you should have a
@@ -78,12 +101,19 @@ An example for the label names .yaml file:
 
     names: [cat, dog]
 
-You can use the output of the lightly-crop command as the *input_dir* for your
-lightly-train command.
+You can use the output of the lightly-crop-deprecated command as the *input_dir* for your
+lightly-train-deprecated command.
 
 Training and Embedding in a Go – Magic
 ---------------------------------------------------
-Lightly-magic is a singular command for training a self-supervised model and use it to compute embeddings
+
+.. warning::
+
+    This functionality is deprecated since version 1.6. The `lightly-magic` command
+    was renamed to `lightly-magic-deprecated` in version 1.6 and will be completely
+    removed in version 1.7.
+
+Lightly-magic-deprecated is a singular command for training a self-supervised model and use it to compute embeddings
 
 * To start with, we need to input the directory of the dataset, pass it to input_dir.
 * It requires information on the number of epochs to perform, set trainer.max_epochs.
@@ -98,43 +128,50 @@ Lightly-magic is a singular command for training a self-supervised model and use
     # Embed images from an input directory
     # Setting trainer.max_epochs=10 trains a model for 10 epochs.
     # loader.num_workers=8 specifies the number of cpu cores used for loading images.
-    lightly-magic input_dir=data_dir trainer.max_epochs=10 loader.num_workers=8
+    lightly-magic-deprecated input_dir=data_dir trainer.max_epochs=10 loader.num_workers=8
 
 
     # To use a custom batch size, pass the batch size to loader.batch_size parameter
     # updating the previous example by passing value for loader.batch_size
-    lightly-magic input_dir=data_dir trainer.max_epochs=10 loader.batch_size=128 \
+    lightly-magic-deprecated input_dir=data_dir trainer.max_epochs=10 loader.batch_size=128 \
     loader.num_workers=8
 
 
 .. _cli-train-lightly:
 
 Train a model using the CLI
 ---------------------------------------
+
+.. warning::
+
+    This functionality is deprecated since version 1.6. The `lightly-train` command
+    was renamed to `lightly-train-deprecated` in version 1.6 and will be completely
+    removed in version 1.7.
+
 Training a model using default parameters can be done with just one command. Let's
 assume you have a folder of cat images named `cat` and want to train a model on it.
 You can use the following command to train a model and save the checkpoint:
 
 .. code-block:: bash
 
     # train a model using default parameters
-    lightly-train input_dir=cat
+    lightly-train-deprecated input_dir=cat
 
     # train a model for 5 epochs
-    lightly-train input_dir=cat trainer.max_epochs=5
+    lightly-train-deprecated input_dir=cat trainer.max_epochs=5
 
     # continue training from a checkpoint for another 10 epochs
-    lightly-train input_dir=cat trainer.max_epochs=10 checkpoint=mycheckpoint.ckpt
+    lightly-train-deprecated input_dir=cat trainer.max_epochs=10 checkpoint=mycheckpoint.ckpt
 
     # continue training from the last checkpoint
-    lightly-train input_dir=cat trainer.max_epochs=10 \
+    lightly-train-deprecated input_dir=cat trainer.max_epochs=10 \
                   checkpoint=$LIGHTLY_LAST_CHECKPOINT_PATH
 
     # train with multiple gpus
     # the total batch size will be trainer.gpus * loader.batch_size
-    lightly-train input_dir=data_dir trainer.gpus=2
+    lightly-train-deprecated input_dir=data_dir trainer.gpus=2
 
-The path to the latest checkpoint you created using the `lightly-train` command
+The path to the latest checkpoint you created using the `lightly-train-deprecated` command
 will be saved under an environment variable named LIGHTLY_LAST_CHECKPOINT_PATH.
 This can be useful for continuing training or for creating embeddings from
 a checkpoint.
@@ -143,7 +180,7 @@ For a full list of supported arguments run
 
 .. code-block:: bash
     
-    lightly-train --help
+    lightly-train-deprecated --help
 
 
 You can get an overview of the various CLI parameters you can set in 
@@ -159,15 +196,15 @@ Once you have a trained model checkpoint, you can create an embedding of a datas
 .. code-block:: bash
 
     # use pre-trained models provided by Lighly
-    lightly-embed input_dir=cat
+    lightly-embed-deprecated input_dir=cat
 
     # use custom checkpoint
-    lightly-embed input_dir=cat checkpoint=mycheckpoint.ckpt
+    lightly-embed-deprecated input_dir=cat checkpoint=mycheckpoint.ckpt
 
     # use the last checkpoint you created
-    lightly-embed input_dir=cat checkpoint=$LIGHTLY_LAST_CHECKPOINT_PATH
+    lightly-embed-deprecated input_dir=cat checkpoint=$LIGHTLY_LAST_CHECKPOINT_PATH
 
-The path to the latest embeddings you created using the `lightly-embed` command
+The path to the latest embeddings you created using the `lightly-embed-deprecated` command
 will be saved under an environment variable named LIGHTLY_LAST_EMBEDDING_PATH.
 
 The embeddings.csv file should look like the following:
@@ -197,40 +234,37 @@ without the need to download them explicitly.
 .. code-block:: bash
 
     # download a list of files
-    lightly-download tag_name=my_tag_name dataset_id=your_dataset_id token=your_token
+    lightly-download-deprecated tag_name=my_tag_name dataset_id=your_dataset_id token=your_token
 
     # download the images and store them in an output directory
-    lightly-download tag_name=my_tag_name dataset_id=your_dataset_id token=your_token \
+    lightly-download-deprecated tag_name=my_tag_name dataset_id=your_dataset_id token=your_token \
                      output_dir=path/to/output/dir
 
     # copy images from an input directory to an output directory
-    lightly-download tag_name=my_tag_name dataset_id=your_dataset_id token=your_token \
+    lightly-download-deprecated tag_name=my_tag_name dataset_id=your_dataset_id token=your_token \
                      input_dir=path/to/input/dir output_dir=path/to/output/dir
 
 .. _ref-breakdown-lightly-magic:
 
-Breakdown of lightly-magic
---------------------------
+Breakdown of lightly-magic-deprecated
+-------------------------------------
+
+.. warning::
+
+    This functionality is deprecated since version 1.6. The `lightly-magic` command
+    was renamed to `lightly-magic-deprecated` in version 1.6 and will be completely
+    removed in version 1.7.
 
-If you want to break the lightly-magic command into separate steps,
+If you want to break the lightly-magic-deprecated command into separate steps,
 you can use the following:
 
 .. code-block:: bash
 
-    # lightly-magic command
-    lightly-magic input_dir=data_dir
+    # lightly-magic-deprecated command
+    lightly-magic-deprecated input_dir=data_dir
     # equivalent breakdown into single commands
 
     # train the embedding model
-    lightly-train input_dir=data_dir
+    lightly-train-deprecated input_dir=data_dir
     # embed the images with the embedding model just trained
-    lightly-embed input_dir=data_dir checkpoint=$LIGHTLY_LAST_CHECKPOINT_PATH
-
-
-
-
-    
-
-
-
-
+    lightly-embed-deprecated input_dir=data_dir checkpoint=$LIGHTLY_LAST_CHECKPOINT_PATH

docs/source/lightly.cli.rst

@@ -50,15 +50,15 @@ and empty string so it must be overwritten:
 .. code-block:: bash
 
    # train the default model on my data
-   lightly-train input_dir='path/to/my/data'
+   lightly-train-deprecated input_dir='path/to/my/data'
 
 An argument which is grouped under a certain namespace can be accessed by specifying the namespace and the argument,
 separated by a dot. For example the argument "name" in the namespace "model" can be accessed like so:
 
 .. code-block:: bash
 
    # train a ResNet-34 on my data
-   lightly-train input_dir='path/to/my/data' model.name='resnet-34'
+   lightly-train-deprecated input_dir='path/to/my/data' model.name='resnet-34'
 
 Additional Arguments
 ^^^^^^^^^^^^^^^^^^^^^
@@ -71,7 +71,7 @@ This can be done by adding a + right before the argument:
 .. code-block:: bash
 
    # train a ResNet-34 with momentum on my data
-   lightly-train input_dir='path/to/my/data' model.name='resnet-34' +optimizer.momentum=0.9
+   lightly-train-deprecated input_dir='path/to/my/data' model.name='resnet-34' +optimizer.momentum=0.9
 
 .. _ref-cli-config-default:
 

lightly/cli/__init__.py

@@ -1,6 +1,19 @@
 """ The lightly.cli module provides a console interface
     for training self-supervised models, embedding,
     and filtering datasets
+
+    Warning: Most commands of the CLI are deprecated since version 1.6.
+    
+    The following commands were renamed in version 1.6 and will be removed in version
+    1.7:
+    - `lightly-crop` -> `lightly-crop-deprecated`
+    - `lightly-train` -> `lightly-train-deprecated`
+    - `lightly-embed` -> `lightly-embed-deprecated`
+    - `lightly-magic` -> `lightly-magic-deprecated`
+
+    If you would like to continue using these commands, please create an issue on the
+    issue tracker at https://github.com/lightly-ai/lightly/issues or contact us
+    at [email protected]
 """
 
 # Copyright (c) 2020. Lightly AG and its affiliates.

lightly/cli/config/config.yaml

@@ -121,26 +121,40 @@ hydra:
       == Description ==
       The lightly Python package is a command-line tool for self-supervised learning.
 
+      == Warning ==
+      Most commands of the CLI are deprecated since version 1.6.
+
+      The following commands were renamed in version 1.6 and will be removed in version
+      1.7:
+      - `lightly-crop` -> `lightly-crop-deprecated`
+      - `lightly-train` -> `lightly-train-deprecated`
+      - `lightly-embed` -> `lightly-embed-deprecated`
+      - `lightly-magic` -> `lightly-magic-deprecated`
+
+      If you would like to continue using these commands, please create an issue on the
+      issue tracker https://github.com/lightly-ai/lightly/issues> or contact us at
+      [email protected]
+
     footer: |
       == Examples ==
 
       Use a pre-trained resnet-18 to embed your images
-      > lightly-embed input='path/to/image/folder' collate.input_size=224
+      > lightly-embed-deprecated input='path/to/image/folder' collate.input_size=224
 
       Load a model from a custom checkpoint to embed your images
-      > lightly-embed input_dir='path/to/image/folder' collate.input_size=224 checkpoint='path/to/checkpoint.ckpt'
+      > lightly-embed-deprecated input_dir='path/to/image/folder' collate.input_size=224 checkpoint='path/to/checkpoint.ckpt'
 
       Train a self-supervised model on your image dataset from scratch
-      > lightly-train input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224 pre_trained=False
+      > lightly-train-deprecated input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224 pre_trained=False
 
       Train a self-supervised model starting from the pre-trained checkpoint
-      > lightly-train input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224
+      > lightly-train-deprecated input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224
 
       Train a self-supervised model starting from a custom checkpoint
-      > lightly-train input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224 checkpoint='path/to/checkpoint.ckpt'
+      > lightly-train-deprecated input_dir='path/to/image/folder' loader.batch_size=128 collate.input_size=224 checkpoint='path/to/checkpoint.ckpt'
 
       Train using half-precision
-      > lightly-train input_dir='path/to/image/folder' trainer.precision=16
+      > lightly-train-deprecated input_dir='path/to/image/folder' trainer.precision=16
       
       Download a list of files in a given tag from the Lightly Platform
       > lightly-download tag_name='my-tag' dataset_id='your_dataset_id' token='your_access_token'

lightly/cli/crop_cli.py

@@ -1,8 +1,14 @@
 # -*- coding: utf-8 -*-
 """**Lightly Train:** Train a self-supervised model from the command-line.
 
-This module contains the entrypoint for the **lightly-train**
+This module contains the entrypoint for the **lightly-crop-deprecated**
 command-line interface.
+
+Warning: This functionality is deprecated since version 1.6. The `lightly-crop` command
+was renamed to `lightly-crop-deprecated` in version 1.6 and will be completely removed
+in version 1.7. If you would like to continue using the command, please create an issue
+on the issue tracker at https://github.com/lightly-ai/lightly/issues or contact us at
+[email protected]
 """
 
 # Copyright (c) 2020. Lightly AG and its affiliates.
@@ -76,6 +82,12 @@ def _crop_cli(cfg, is_cli_call=True):
 def crop_cli(cfg):
     """Crops images into one sub-image for each object.
 
+    Warning: This functionality is deprecated since version 1.6. The lightly-crop
+    command was renamed to lightly-crop-deprecated in version 1.6 and will be
+    completely removed in version 1.7. If you would like to continue using the
+    command, please create an issue on the issue tracker at
+    https://github.com/lightly-ai/lightly/issues or contact us at [email protected]
+
     Args:
         cfg:
             The default configs are loaded from the config file.
@@ -102,10 +114,10 @@ def crop_cli(cfg):
 
     Examples:
         >>> # Crop images and set the crop to be 20% around the bounding box
-        >>> lightly-crop input_dir=data/images label_dir=data/labels output_dir=data/cropped_images crop_padding=0.2
+        >>> lightly-crop-deprecated input_dir=data/images label_dir=data/labels output_dir=data/cropped_images crop_padding=0.2
 
         >>> # Crop images and use the class names in the filename
-        >>> lightly-crop input_dir=data/images label_dir=data/labels output_dir=data/cropped_images label_names_file=data/data.yaml
+        >>> lightly-crop-deprecated input_dir=data/images label_dir=data/labels output_dir=data/cropped_images label_names_file=data/data.yaml
 
     """
     return _crop_cli(cfg)