> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/get-started/cli-quickstart.md).

# CLI quickstart

Configure the CLI, create a project, upload data, wait for processing, and emit JSON for automation.

Upload two local images to a new Unitlab project and check that they are ready to open. These commands use **Unitlab CLI 3.1.3** in a macOS or Linux shell.

## Before you start

[Install the CLI](/api-sdk-cli/get-started/install-the-python-sdk-and-cli.md) and [configure your API key](/api-sdk-cli/get-started/authentication-and-configuration.md). Prepare two valid images with this structure, then open a terminal in `road-scenes/`:

```
road-scenes/
└── images/
    ├── road.jpg
    └── crossing.jpg
```

The names are examples. Keep annotation JSON outside the media folder; label import is a separate workflow.

## 1. Create a project

```bash
unitlab project create "Road scenes" --json
```

Copy the returned project `id` into `PROJECT_ID` below. To reuse a project, find its ID with `unitlab project list --json` instead of creating another one.

```bash
PROJECT_ID="YOUR_PROJECT_ID"
```

## 2. Upload the images

```bash
unitlab project upload "$PROJECT_ID" --source ./images --json
```

For two files accepted without upload errors, the response has this shape. The Batch Queue ID will be different for your upload:

```json
{
  "total": 2,
  "uploaded": 2,
  "failed": 0,
  "batch_queue_id": "YOUR_BATCH_QUEUE_ID"
}
```

This is the upload result. Server processing may still be running. A partial upload returns a nonzero exit code even when some files succeeded; inspect the response and keep its Batch Queue ID before retrying anything.

## 3. Wait for processing

Set `BATCH_QUEUE_ID` to the value from the upload response:

```bash
BATCH_QUEUE_ID="YOUR_BATCH_QUEUE_ID"
unitlab batch-queue wait "$PROJECT_ID" "$BATCH_QUEUE_ID" --timeout 1800
```

Check the returned `failed` count. Waiting can finish with failed items. If the command times out, use the same project and Batch Queue IDs to monitor the existing upload.

## 4. Verify the uploaded items

```bash
unitlab project data-units "$PROJECT_ID" --batch-queue "$BATCH_QUEUE_ID" --json
```

For this example, expect separate Data Units for `road.jpg` and `crossing.jpg`. Open both in **Project Data** to confirm they render correctly. Their presence does not imply annotation or approval.

Use `--json` when a script reads command output. For the options installed on your machine, run `unitlab project upload --help` or `unitlab batch-queue wait --help`.

## Upload guides

* [Project files and folders](/api-sdk-cli/sdks/project-uploads.md) with the Python SDK.
* [CLI project uploads](/api-sdk-cli/clis/cli-projects-and-data-units.md) and [CLI Asset uploads](/api-sdk-cli/clis/cli-assets-and-folders.md).
* [Data Group automation](/api-sdk-cli/sdks/data-group-automation.md) using filename rules.
* [Annotation imports](/api-sdk-cli/sdks/annotation-imports.md), available through the Python SDK. Version 3.1.3 does not include an annotation-import CLI command.

## Continue the workflow

Import existing labels with the [Python SDK](/api-sdk-cli/sdks/annotation-imports.md) or the [Unitlab interface](https://docs.unitlab.ai/documentation/data/import-local-annotations). CLI 3.1.3 uploads media but has no annotation-import command. Configure the project ontology and workflow before assigning annotation or review work.

***

> **Explore related Unitlab capabilities:** [enterprise data annotation workflows](https://unitlab.ai/en/data-annotation)