Command line interface

Encord Active is equipped with a command line interface (CLI) that simplifies your interaction with the platform.
With the CLI, you can easily initialize projects, import projects and labels, manage and run metrics, and launch the application.

We strive to ensure that our CLI is self-explanatory, eliminating the need for frequent switching between the terminal and documentation.

Simply run encord-active --help to get details about all the top-level commands and encord-active COMMAND --help

Here is a list of all the top-level commands:

quickstart         Start Encord Active straight away 🏃💨
download           Download a sandbox dataset to get started 📁
init               Initialize a project from your local file system 🌱
import             Import projects or predictions ⬇️
refresh            Sync data and labels from a remote Encord project 🔄
start              Launch the application with the provided project ✨
project            Manage project settings ⚙️
metric             Manage project metrics 📋
print              Print useful information 🖨️
config             Configure global settings 🔧

quickstart

The command will download a small example project to a subdirectory named quickstart in the current working directory and automatically launch the application.

Usage: encord-active quickstart [OPTIONS]

Options:
 --target  -t  DIRECTORY  Directory where the project would be saved.

download

In addition to the quickstart example, there are a several other open-source datasets available for download that you can use to explore the capabilities of Encord Active.

The command will display a list of available sandbox projects, allowing you to select one from the menu interactively.
If you prefer to skip the interactive selection, you can directly specify the sandbox project name using the --project-name optional argument.

Usage: encord-active download [OPTIONS]

Options:
 --project-name      TEXT       Name of the chosen project.
 --target        -t  DIRECTORY  Directory where the project would be saved.

start

Launch the application with the provided project ✨

Usage: encord-active start [OPTIONS]

Options:
 --target  -t  DIRECTORY  Path of the projects you would like to start

init

The command initializes new project from locally stored images and labels. It will search for images based on the data-glob arguments. By default, all jpeg, jpg, png, and tiff files will be matched.

It will also search for labels if the label-glob and transformer options are provided.
Both glob results will be passed to your implementation of the LabelTransformer interface if you specify the transformer argument.

Usage: encord-active init [OPTIONS] ROOT

Arguments:
 * root              DIRECTORY  The root directory of the dataset you are trying to import

Options:
 --data-glob    -dg  TEXT       Glob pattern to choose files. Repeat the `--data-glob` argument to
                                match multiple globs.
 --label-glob   -lg  TEXT       Glob pattern to choose label files. Repeat the `--label-glob`
                                argument to match multiple globs. This argument is only used if you
                                also provide the `transformer` argument.
 --target       -t   DIRECTORY  Directory where the project would be saved.
 --name         -n   TEXT       Name to give the new project. If no name is provided, the root
                                directory will be used with '[EA] ' prepended.
 --symlinks                     Use symlinks instead of copying images to the target directory.
 --dryrun                       Print the files that will be imported WITHOUT importing them.
 --no-metrics                   Skip metrics execution on the initiated project.
 --transformer       PATH       Path to python module with one or more implementations of the
                                `encord_active.lib.labels.label_transformer.LabelTransformer`
                                interface.

The Quick import data & labels workflow is a great starting point for utilizing this command.

import

This command is used to import projects and predictions from different sources.

Refer to the import section for examples of specific use-cases.

Usage: encord-active import [OPTIONS] COMMAND [ARGS]...

Import Projects or Predictions ⬇️

Commands:
 predictions  Imports a predictions file. The predictions should be using the `Prediction` model
              and be stored in a pkl file.
              If the `--coco` option is specified then the file should be a json following the COCO results format. 🧠
 project      Imports a new project from Encord or a local COCO project. 📦

project

Imports a new project from Encord or a local COCO project.

Usage: encord-active import project [OPTIONS]

Encord Project Arguments:
 --project-hash            TEXT       Encord project hash of the project you wish to import.
                                      Leaving it blank will allow you to choose one interactively.
 --store-data-locally                 Store project data locally to avoid the need for on-demand download when visualizing and analyzing it. 

COCO Project Arguments:
 --coco                               Import a project from the COCO format.
 --images              -i  DIRECTORY  Path to the directory containing the dataset images.
 --annotations         -a  FILE       Path to the file containing the dataset annotations.
 --symlinks                           Use symlinks instead of copying COCO images to the target directory.

Options:
 --target              -t  DIRECTORY  Directory where the project would be saved.

predictions

Imports a predictions file. The predictions should be using the Prediction model and be stored in a pkl file.
If the --coco option is specified then the file should be a json following the COCO results format.

Refer to the Import model predictions section for specific usage examples.

Usage: encord-active import predictions [OPTIONS] PREDICTIONS_PATH

Arguments:
 * predictions_path      FILE       Path to a predictions file.

Options:
 --target            -t  DIRECTORY  Path to the target project.
 --coco                             Import a COCO results format file.

refresh

Sync data and labels from a remote Encord project.

Usage: encord-active refresh [OPTIONS]

Options:
 --target  -t  DIRECTORY  Path to the target project.

The local project should have a reference to the remote Encord project in its config file (project_meta.yaml).
The required attributes are:

1. The remote flag set to true.
2. The hash of the remote Encord project.
3. The path to the private Encord user SSH key.

This command works in local projects created via encord-active import project and those successfully exported to Encord from the "Actions" tab in the UI's toolbox.

project

Manage project settings ⚙️

Usage: encord-active project [OPTIONS] COMMAND [ARGS]...

Commands:
 download-data     Download all data locally for improved responsiveness.

download-data

Store project data locally to avoid the need for on-demand download when visualizing and analyzing it.

Usage: encord-active project download-data [OPTIONS]

Options:
 --target  -t  DIRECTORY  Path to the target project.

metric

Manage project metrics.

Usage: encord-active metric [OPTIONS] COMMAND [ARGS]...

Commands:
 add               Add metrics.
 list              List metrics.
 remove            Remove metrics.
 run               Run metrics.
 show              Show information about available metrics.

ℹ️

Note

Make sure your shell's current working directory is that of an Encord Active project, or your command points to one with the --target global option.

add

Add metrics to the project by specifying the path to a metrics module and the titles of the desired metrics within the module.
If no metric titles are provided, all metrics found in the Python module will be automatically added to the project.

Usage: encord-active metric add [OPTIONS] MODULE_PATH [METRIC_TITLE]...

Arguments:
 *  module_path       FILE               Path to the python module where the metric resides.
    metric_title      [METRIC_TITLE]...  Title of the metric. Can be used multiple times.

Options:
 --target         -t  DIRECTORY          Path to the target project.

If you attempt to add a metric that already exists, it will be skipped, and you will be notified accordingly.
However, if a metric title is not found in the Python module, an error will occur.
Please ensure that the metric titles are accurate and correspond to the metrics available in the module.

🚧

Caution

Some terminals may treat square braces ([ and ]) as special characters. It is advisable to always quote arguments containing these characters to prevent unexpected shell expansion.

remove

Removes metrics from a project.

Usage: encord-active metric remove [OPTIONS] METRIC_TITLE...

Arguments:
 * metric_title      METRIC_TITLE...  Title of the metric. Can be used multiple times.

Options:
 --target        -t  DIRECTORY        Path to the target project.

list

List metrics in the project, including editables. Metrics are listed in a case-insensitive sorted order.

Usage: encord-active metric list [OPTIONS]

Options:
 --target  -t  DIRECTORY  Path to the target project.

run

Run metrics on project data and labels.

Usage: encord-active metric run [OPTIONS] [METRIC_TITLE]...

Arguments:
 metric_title      [METRIC_TITLE]...  Title of the metric. Can be used multiple times.

Options:
 --target      -t  DIRECTORY          Path to the target project.
 --all                                Run all metrics.
 --fuzzy                              Enable fuzzy search in the selection. (press [TAB] or [SPACE] to select more than one) 🪄

show

Show information about one or more available metrics in the project.

Usage: encord-active metric show [OPTIONS] METRIC_TITLE...

Arguments:
 * metric_title      METRIC_TITLE...  Title of the metric. Can be used multiple times.

Options:
 --target        -t  DIRECTORY        Path to the target project.

config

Encord Active keeps some configurable properties to prevent repetitive input prompts.

The config file is stored at:

• Linux: ~/.config/encord-active/config.toml
• MacOS: ~/Library/Application Support/encord-active/config.toml
• Windows: %APPDATA%/encord-active/config.toml

ssh_key_path = "/absolute/path/to/ssh-key" # The API key to use when accessing remote Encord projects

Usage: encord-active config [OPTIONS] COMMAND [ARGS]...

Commands:
 get               Print the value of an Encord Active configuration property.
 list              List Encord Active configuration properties.
 set               Sets an Encord Active configuration property.
 unset             Unsets the value of an Encord Active configuration property.

print

Print useful information.

Usage: encord-active print [OPTIONS] COMMAND [ARGS]...

Commands:
 data-mapping      Prints a mapping between `data_hashes` and their corresponding `filename`.
 encord-projects   Print the mapping between `project_hash`es of your Encord projects and their titles.
 ontology          Prints an ontology mapping between the class name to the `featureNodeHash` JSON format.
 system-info       Prints the information of the system for the purpose of bug reporting.

Options:
 --json            Save output to a json file.