CLI Resource Management

Perform headless management of your Highlighter environment using the CLI.

Overview

The Highlighter CLI (hl) supports lifecycle management of core system resources, allowing "headless" operation, automation scripts, and cleanup tasks without needing to access the web interface.

You can manage the following resources directly from your terminal:

Cases: hl case
Entities: hl entity
Object Classes: hl object-class
Task Definitions: hl task-definition
Tasks: hl task
Workflow Steps: hl step
Workflows: hl workflow & hl workflow-order
Experiments & Training: hl experiment, hl evaluation, hl training-run
Pipelines: hl pipeline-instance

Use the --help flag with any command to see available options:

hl task-definition --help
hl entity --help

Pass --quiet (or -q) before the subcommand to suppress warnings and informational logging, leaving only command output and errors — useful when scripting, since it drops the noise without affecting the JSON on stdout:

hl --quiet case list --workflow-order-id <ORDER_ID>

Task Definitions

Task definitions configure how a machine assessment step processes data — which machine agent to use, the object class to create entities for, and how to map fields from the source file.

# List all task definitions
hl task-definition list

# Filter by task type
hl task-definition list --task-type KmlToEntity::EntityDetection

# Read a single task definition
hl task-definition read --id <UUID>

# Create a task definition
hl task-definition create \
  --name "Import Pole Entities" \
  --task-type "KmlToEntity::EntityDetection" \
  --object-class-id <OBJECT_CLASS_UUID> \
  --entity-external-id-type "Pole" \
  --entity-external-id-field-name "SITE_LABEL"

# Delete a task definition
hl task-definition delete --id <UUID>

Supported --task-type values:

Task Type	Description
`Review`	Human review step (no machine agent)
`KmlToEntity::EntityDetection`	Import entities from KML files
`DbfToEntity::EntityDetection`	Import entities from DBF (Shapefile attribute) files

Object Classes

# List all object classes in the account
hl object-class list

# Filter by name (case-insensitive substring match)
hl object-class list --name Pole

# Cap the number returned
hl object-class list --limit 20

# Read specific object classes once you know their name or ID
hl object-class read --names Pole Vehicle
hl object-class read --ids 1 2 3

hl object-class list is the way to discover object class names and IDs when you don't already know them — hl object-class read requires you to name the classes you want up front.

Tasks

# Add files to a workflow order — creates cases and tasks automatically
hl task create --workflow-order-id <ORDER_ID> --file-ids <FILE_ID_1> --file-ids <FILE_ID_2>

# Create a task on a case that already exists (e.g. one made with `hl case create` or `hl case copy`)
hl task create --case-id <CASE_ID> --step-id <STEP_ID>

--case-id/--step-id attaches a task directly to an existing case, which is the only way to give a case created via the CLI something for hl agent start to run. --step-id is required with --case-id.

Workflow Orders

Workflow orders group a batch of files to be processed through a workflow.

# List orders for a workflow
hl workflow-order list --workflow-id <WORKFLOW_ID>

# Create a new order
hl workflow-order create \
  --name "Site Survey Batch 1" \
  --workflow-id <WORKFLOW_ID> \
  --state approved

# Create a draft order (files can be added before approving)
hl workflow-order create \
  --name "Pending Import" \
  --workflow-id <WORKFLOW_ID> \
  --state draft

# Delete an order
hl workflow-order delete --id <ORDER_ID>

The --state flag accepts draft or approved (default: approved).

The optional --case-matching-strategy flag controls how files are matched to cases: geolocation, ingestion_path, or none.

Workflow Steps

Machine Assessment Steps

Create a machine assessment step and automatically assign its agent based on the task definition:

hl step create-machine-assessment \
  --name "DBF Entity Import" \
  --workflow-id <WORKFLOW_ID> \
  --task-definition-id <TASK_DEFINITION_UUID>

The agent is selected automatically from the task definition's task_type — no manual agent assignment required.

To chain this step after an existing step:

hl step create-machine-assessment \
  --name "DBF Entity Import" \
  --workflow-id <WORKFLOW_ID> \
  --task-definition-id <TASK_DEFINITION_UUID> \
  --previous-step-id <PRECEDING_STEP_ID>

Cases

Manage the cases within your workflows.

# Create a new case
hl case create --workflow-order-id <ORDER_ID> --title "My Case"

# Get a single case, including its data file IDs and tasks
hl case get --id <CASE_ID>

# List the cases in a workflow order
hl case list --workflow-order-id <ORDER_ID> --limit 50

# Copy a case onto a new case over the same data files
hl case copy --id <CASE_ID>

# Download a case's files into <OUTPUT_DIR>/<CASE_ID>/
hl case export --id <CASE_ID> --output-dir <OUTPUT_DIR>

# Download only the video and image files
hl case export --id <CASE_ID> --output-dir <OUTPUT_DIR> --content-type VIDEO --content-type IMAGE

# Delete a specific case
hl case delete --id <CASE_ID>

# Add a message to a case
hl case message create --case-id <CASE_ID> --content "Please review this."

hl case get reports the data file IDs and tasks attached to a case — exactly the input hl case create expects, which is what makes a case reproducible from the CLI. It reads the case only: no files are downloaded. (hl case read still works as a deprecated alias of hl case get, and warns on stderr.)

hl case list is the separate collection query — without --workflow-order-id it lists the account's cases, most recent first, 25 at a time unless you raise --limit.

hl case export is the one that writes to disk. The downloaded payloads land in <OUTPUT_DIR>/<CASE_ID>/data_files/, next to a case.json, a manifest.json, and (unless you pass --no-include-messages) a messages.json. Use --file-structure to choose how the files are named, and -B/-A (hh:mm:ss) to pad the data-source time window either side of the case.

Downloading only some of a case's files

A case that spans a video stream and a set of observations can export a lot more than you need. --content-type (short form -C) restricts the download to files of the types you name:

Value	Value	Value
`IMAGE`	`VIDEO`	`TEXT`
`JSON`	`AUDIO`	`WEB_PAGE`
`KML`	`LIDAR`	`OBSERVATION`
`CSV`	`DBF`

The option is case-insensitive and repeatable — give it once per type you want, as in the example above. Omit it and every file is downloaded, which is the behaviour you get without the flag.

The filter applies to both halves of an export: the files attached to the case's latest submission, and the files pulled from its data sources across the case's time window. The filter that was applied is recorded in manifest.json under contentTypes, so an export directory says for itself whether it holds everything or a subset.

hl case copy creates a new case over the same data files as the source case (matched by data file UUID), carrying across its entity, description, and importance. The copy always starts in the ready state, even if the source case was completed, since state itself does not travel with the copy. Useful for re-running an agent over the same inputs without disturbing the original case. Pass --workflow-order-id to place the copy in a different order, or --state draft to hold it back.

Entities

# List entities (default: 100 most recent)
hl entity list

# Filter and format
hl entity list \
  --object-class-uuid <UUID> \
  --external-id-type Pole \
  --limit 50 \
  --format json

# Count entities matching filters
hl entity count
hl entity count --external-id-type Pole
hl entity count --object-class-uuid <UUID>

# Delete an entity
hl entity delete --id <ENTITY_ID>

hl entity count is useful for verifying the result of a bulk import without paging through all records.

Workflows

# List workflows
hl workflow list

# Delete a workflow
hl workflow delete --id <WORKFLOW_ID>

Experiments & Research

Experiments

# Read experiment details to a markdown file
hl experiment read --id <EXPERIMENT_ID> --save-dir ./output

# Delete an experiment
hl experiment delete --id <EXPERIMENT_ID>

Evaluations

# List all evaluations
hl evaluation list

# Read a specific evaluation
hl evaluation read --id <EVALUATION_ID>

# Create a new evaluation
hl evaluation create --title "Model v2 Benchmark" --assigned-to-id <USER_ID> \
  --description "Benchmark description" \
  --objective "Measure model accuracy" \
  --evaluation-process "Run inference and score predictions"

# Manage metrics within an evaluation
hl evaluation metric list --evaluation-id <EVALUATION_ID>
hl evaluation metric create --evaluation-id <EVALUATION_ID> --code Accuracy --name "Test Accuracy"

# Record evaluation results
hl evaluation result create --metric-id <METRIC_ID> --value 0.95

# Delete an evaluation
hl evaluation delete --id <EVALUATION_ID>

Training Runs

# Create a training run
hl training-run create \
  --evaluation-id <EVAL_ID> \
  --experiment-id <EXP_ID> \
  --capability-id <MODEL_ID> \
  --workflow-id <WORKFLOW_ID> \
  --name "Run v1"

# Read training run configuration
hl training-run read <RUN_ID> -o config.yaml

# Delete a training run
hl training-run delete --id <RUN_ID>

# Download a training run artefact
hl training-run artefact read --id <RUN_ID> --artefact-type OnnxOpset14 --save-path ./model.onnx

Pipelines

# Delete a pipeline instance
hl pipeline-instance delete --id <INSTANCE_ID>