Skip to main content

CLI Workflows

End-to-end examples for common tasks using the vfrog CLI. These workflows assume you have already installed the CLI and logged in.

Quick Start​

A minimal workflow from login to inference:

# Log in and set context
vfrog login
vfrog config set organisation --organisation_id <org_id>
vfrog config set project --project_id <project_id>

# Upload dataset images
vfrog dataset_images upload https://example.com/img1.jpg https://example.com/img2.jpg

# Create an object and set it as active
vfrog objects create https://example.com/product.jpg --label "My Product"
vfrog config set object --object_id <object_id>

# Create iteration, run SSAT, and wait for completion
vfrog iterations create <object_id>
vfrog iterations ssat --iteration_number 1
vfrog iterations status --iteration_number 1 --watch

# Train, deploy, and export
vfrog iterations train --iteration_number 1
vfrog iterations status --iteration_number 1 --watch
vfrog iterations deploy --iteration_number 1
vfrog export yolo --iteration_id <id> --output ./my-dataset

Training a Model from Scratch​

Step 1: Upload Dataset Images​

Dataset images are the images your model will learn to search through. Choose the method that fits your workflow:

From URLs:

vfrog dataset_images upload https://example.com/image1.jpg https://example.com/image2.jpg

From a local directory:

vfrog dataset_images upload --dir ./my-images/

From a single local file:

vfrog dataset_images upload --file ./photo.jpg

From a CSV file (bulk import):

vfrog dataset_images import --csv ./images.csv

CSV format (header row required, only image_url is mandatory):

image_url,external_id,label
https://example.com/img1.jpg,EXT001,scene_1
https://example.com/img2.jpg,EXT002,scene_2
note

Images uploaded from URLs are downloaded and re-uploaded to vfrog's CDN. The original URLs do not need to remain accessible after upload.

Step 2: Create an Object​

Objects are the product/reference images your model learns to detect:

# From URL
vfrog objects create https://example.com/product.jpg --label "Sneaker" --external_id "SKU123"

# From local file
vfrog objects create --file ./product.jpg --label "Sneaker" --external_id "123"

# Set as active object
vfrog config set object --object_id <object_id>

Step 3: Create an Iteration and Run SSAT​

# Create iteration (randomly selects 20 dataset images by default)
vfrog iterations create <object_id>

# Or create with a specific number of random images
vfrog iterations create <object_id> --random 50

# Start SSAT annotation
vfrog iterations ssat --iteration_number 1

# Watch progress until completion
vfrog iterations status --iteration_number 1 --watch

Supported industries: Retail, Agriculture, Aquaculture, Fisheries, Manufacturing, Mechanical Engineering, PPE

You can skip the automatic industry detection by specifying it directly:

vfrog iterations ssat --iteration_number 1 --industry Retail

Step 4: Review Annotations​

View annotations produced by SSAT:

# Table view with bounding box counts
vfrog iterations annotations --iteration_number 1

# Full annotation details in JSON
vfrog iterations annotations --iteration_number 1 --json

Open the HALO web UI to review and correct annotations:

vfrog iterations halo --iteration_number 1

Step 5: Train and Deploy​

# Train a YOLO model
vfrog iterations train --iteration_number 1
vfrog iterations status --iteration_number 1 --watch

# Deploy to production
vfrog iterations deploy --iteration_number 1

Step 6: Run Inference​

# Single image inference
vfrog inference --api-key <key> --image_url https://example.com/test.jpg

# Local file
vfrog inference --api-key <key> --image ./local.jpg

Iterative Improvement​

After training iteration 1, create iteration 2+ to improve your model. Subsequent iterations use the trained model from the previous iteration for annotation.

# Create the next iteration from the current one
vfrog iterations next --iteration_number 1

# Run SSAT on the new iteration (uses model from iteration 1)
vfrog iterations ssat --iteration_number 2
vfrog iterations status --iteration_number 2 --watch

# Review, train, and deploy
vfrog iterations train --iteration_number 2
vfrog iterations status --iteration_number 2 --watch
vfrog iterations deploy --iteration_number 2

If an iteration needs to be re-run from scratch:

# Restart an iteration (delete and recreate)
vfrog iterations restart --iteration_id <id>

# Restart and immediately run SSAT
vfrog iterations ssat --iteration_id <id> --restart

Batch Inference​

Process up to 10 images at once:

# Batch inference with URLs
vfrog inference batch --api-key <key> --image_url "url1,url2,url3"

# With an external ID for tracking
vfrog inference batch --api-key <key> --image_url "url1,url2" --external_id "batch-001"

# Check batch status
vfrog inference status <request_id> --api-key <key>

Exporting Datasets​

YOLO Format​

Exports images, YOLO label files, and a data.yaml configuration:

vfrog export yolo --iteration_id <id> --output ./my-dataset

# With ZIP archive
vfrog export yolo --iteration_id <id> --output ./my-dataset --zip

Output structure:

my-dataset/
  images/        # Downloaded dataset images
  labels/        # YOLO format annotations (class_id center_x center_y width height)
  data.yaml      # Class names, train/val split (90/10)

JSON Format​

Export all annotation data as a structured JSON file:

vfrog export json --iteration_id <id> --output ./annotations.json

The JSON file contains full annotation arrays with bounding box coordinates, dataset image metadata, and export timestamps.

CI/CD Pipeline Example​

Use the CLI in automated pipelines with non-interactive login and JSON output:

#!/bin/bash
set -euo pipefail

# Download and install the CLI
curl -L https://github.com/vfrog-ai/vfrog-cli/releases/latest/download/vfrog-linux-amd64 -o vfrog
chmod +x vfrog

# Authenticate non-interactively
./vfrog login --email "$CI_EMAIL" --password "$CI_PASSWORD"

# Set context
./vfrog config set organisation --organisation_id "$ORG_ID"
./vfrog config set project --project_id "$PROJECT_ID"

# Upload images from a directory
./vfrog dataset_images upload --dir ./training-images/

# Create object and capture its ID
./vfrog objects create https://cdn.example.com/product.jpg --label "Widget"
OBJECT_ID=$(./vfrog objects list --json | jq -r '.[0].id')
./vfrog config set object --object_id "$OBJECT_ID"

# Create iteration and run SSAT
./vfrog iterations create "$OBJECT_ID" --random 100
./vfrog iterations ssat --iteration_number 1
./vfrog iterations status --iteration_number 1 --watch

# Train and wait
./vfrog iterations train --iteration_number 1
./vfrog iterations status --iteration_number 1 --watch

# Deploy to production
./vfrog iterations deploy --iteration_number 1

# Export results
ITER_ID=$(./vfrog iterations list --json | jq -r '.[0].id')
./vfrog export yolo --iteration_id "$ITER_ID" --output ./dataset --zip
note

All commands support --json output. Combine with jq to extract specific fields in scripts.

Providing Inference Feedback​

Rate inference results to help improve model quality:

# Positive feedback
vfrog inference feedback --request_id <id> --rating 1 --api-key <key>

# Negative feedback
vfrog inference feedback --request_id <id> --rating -1 --api-key <key>

# Neutral
vfrog inference feedback --request_id <id> --rating 0 --api-key <key>

Next Steps​