Roboflow CLI

The roboflow command line tool provides access to the Roboflow platform for managing computer vision projects, datasets, models, and deployments. It's designed for both human developers and AI coding agents.

Full reference: docs.roboflow.com/deploy/sdks/python-cli

Install & authenticate

pip install roboflow
export ROBOFLOW_API_KEY=rf_xxxxx    # recommended for scripts and agents
roboflow auth login                  # or interactive login

Select a Roboflow region

Roboflow uses the US platform by default. To authenticate with the EU data-residency platform, select the region during login:

roboflow auth login --region eu
# The backwards-compatible alias accepts the same option:
roboflow login --region eu

The selection is saved in the Roboflow config file. You can change it later or inspect the effective endpoints with:

roboflow auth set-region eu
roboflow auth status

For CI and other non-interactive environments, set ROBOFLOW_REGION=eu. ROBOFLOW_REGION accepts us or eu (case-insensitive); an environment value takes precedence over the saved region. Explicit per-URL environment or config values such as API_URL continue to take precedence over the region.

For Roboflow staging, set ROBOFLOW_ENVIRONMENT=staging alongside the region; it accepts prod (default) or staging, and anything else warns and falls back to prod. It selects the roboflow.one (US) or roboflow-eu.one (EU) hosts, matching inference. roboflow auth status reports both switches.

Endpoint	`us` (default)	`eu`
API	`https://api.roboflow.com`	`https://api.roboflow.eu`
App / CLI authentication	`https://app.roboflow.com`	`https://app.roboflow.eu`
Object detection	`https://serverless.roboflow.com`	`https://serverless.roboflow.eu`
Instance segmentation	`https://serverless.roboflow.com`	`https://serverless.roboflow.eu`
Classification, keypoint, VLM (`SERVERLESS_URL`)	`https://serverless.roboflow.com`	`https://serverless.roboflow.eu`
Dedicated deployment	`https://roboflow.cloud`	`https://eu.roboflow.cloud`
Universe	`https://universe.roboflow.com`	`https://universe.roboflow.com`
Semantic segmentation	`https://segment.roboflow.com`	not available

Roboflow Universe remains a single global product, so its URL stays on .com in the EU region. Hosted semantic segmentation has no EU deployment, so in the EU region it raises an error instead of sending images to the US endpoint; set SEMANTIC_SEGMENTATION_URL explicitly to override. EU and US use separate authentication backends; obtain EU API keys from https://app.roboflow.eu and log in again after switching if your existing credentials were issued by the other region.

Global flags

Flag	Short	Description
`--json`	`-j`	Structured JSON output (for agents and piping)
`--api-key`	`-k`	API key override
`--workspace`	`-w`	Workspace override
`--quiet`	`-q`	Suppress progress bars and status messages
`--version`		Show version

Flags work in any position: roboflow project list --json and roboflow --json project list are equivalent.

Quick examples

Create a project and upload images

roboflow project create my-project --type object-detection
roboflow image upload photo.jpg -p my-project
roboflow image upload ./dataset-folder/ -p my-project   # smart: detects directory

Supported --type values: object-detection, single-label-classification, multi-label-classification, instance-segmentation, semantic-segmentation, keypoint-detection, action-recognition.

Download a dataset

roboflow version download my-workspace/my-project/3 -f yolov8
roboflow download my-workspace/my-project/3 -f coco   # alias

Run inference

roboflow infer photo.jpg -m my-project/3

Batch Process Asset Library images

# Exact reviewed selection (CPU is the product default):
roboflow batch create --workflow inspect-defects --image-ids img_1,img_2

# Or every current match for a structured RoboQL filter:
roboflow batch create --workflow inspect-defects --query "tag:night-shift"

# Monitor and control the durable job:
roboflow batch status <job-id>
roboflow batch list
roboflow batch abort <job-id>
roboflow batch restart <job-id>

The create response includes taskId, jobId, and requestId. A job continues if the terminal closes. If a create request has an ambiguous network result, retry with the same --request-id to avoid a duplicate. Local folders must first be uploaded into Roboflow; Batch Processing never sends local file contents through an Agent or CLI job-configuration request.

Train, monitor, cancel, stop

# Start training (any architecture). For NAS sweeps, use a NAS parent modelType:
roboflow train start -p my-project -v 3 --type rfdetr-base
roboflow train start -p my-project -v 3 --type rfdetr-nas-parent      # NAS sweep
roboflow train start -p my-project -v 3 --type rfdetr-nas-base-parent # NAS Base sweep
roboflow train start -p my-project -v 3 --type rfdetr-nas-seg-parent  # NAS instance-segmentation

# Cancel an in-flight training (any architecture; NAS-aware):
roboflow train cancel my-project/3
# Pass --continue-if-no-refund to cancel even past the refund window:
roboflow train cancel my-project/3 --continue-if-no-refund

# Graceful early-stop:
roboflow train stop my-project/3

# Run-level training results bundle (NAS leaderboard for NAS runs,
# minimal bundle for non-NAS):
roboflow train results my-project/3

NAS sweeps require the version's validation split to have at least 15 images; the server returns code: "insufficient_validation_images_for_nas" otherwise.

Train recipes — custom hyperparameters & augmentation (v2)

# Inspect a model type's tunable hyperparameter schema, allowed online
# augmentation/preprocessing steps, and a ready-to-edit recipe template:
roboflow train recipe -p my-project -v 3 -m rfdetr-medium

# Start a training from an edited recipe: take the `template` field, tweak
# it (hyperparameters, online augmentation), and submit it. The server
# dense-fills any defaults the recipe leaves out:
roboflow --json train recipe -p my-project -v 3 -m rfdetr-medium | jq .template > recipe.json
# ... edit recipe.json (e.g. set .hyperparameters.lr) ...
roboflow train start -p my-project -v 3 -t rfdetr-medium --train-recipe @recipe.json

--train-recipe accepts inline JSON or a curl-style @file reference; it creates the training through the v2 trainings API and prints the new trainingId instead of blocking — handy for launching sweeps and polling status separately. --epochs is folded into the recipe's hyperparameters unless the recipe already sets epochs.

NAS models — list, star, deploy

# Get a NAS run's modelGroup from training results:
roboflow --json train results my-project/3 | jq -r .modelGroup
# → rfdetrNasGroup-3

# List every model from one NAS run, with hardware/latency/mAP columns:
roboflow model list -p my-project --group rfdetrNasGroup-3

# Star a NAS-trained model (triggers TRT compile for its recommended hardware):
#   Also starts model evaluation when the workspace has Model Evaluation access.
#   --json train results … gives you the modelId per row.
roboflow model star <modelId>
roboflow model star <modelId> --unstar

model star is NAS-only by server-side design; non-NAS modelTypes return code: "MODEL_NOT_NAS".

Update image metadata and tags

# Single image: set metadata + add tags
roboflow image metadata <image_id> -m '{"camera": "cam1"}' --tags "review,v2"

# Remove metadata keys
roboflow image metadata <image_id> --remove-metadata "old_key"

# Remove tags
roboflow image metadata <image_id> --remove-tags "draft"

# Batch: update multiple images (async), poll for completion
roboflow image metadata img1,img2,img3 --tags "processed" --poll

# Batch with timeout
roboflow image metadata img1,img2 -m '{"status": "done"}' --poll --timeout 600

# Tag alias works identically (hidden command)
roboflow image tag <image_id> --tags "review" --remove-tags "draft"

Single image ID updates synchronously. Multiple comma-separated IDs use the batch async endpoint (up to 1000 images). Use --poll to block until completion; without it the command returns the taskId immediately.

Search and export

roboflow search "tag:reviewed" --limit 100
roboflow search "class:person" --export -f coco -l ./export/

Search returns images only unless --media-types asks otherwise. Valid values are image, video, or both:

# Native videos only, with a signed video URL on each hit
roboflow search "*" --media-types video --fields id,filename,url

# Images and videos together
roboflow search "tag:reviewed" --media-types image,video

# Scope to one project
roboflow image search "*" -p my-project --media-types video --fields id,url

Every hit carries mediaType. Video hits add a signed videoUrl when you request the url field; url itself stays the poster frame, so image-only consumers keep a thumbnail for every hit. --media-types is not accepted with --export.

Browse resources

roboflow workspace list
roboflow project list
roboflow project get my-project
roboflow version list -p my-project
roboflow model list -p my-project

Manage folders

roboflow folder list
roboflow folder create "Training Data" --projects proj1,proj2
roboflow folder get <folder-id>
roboflow folder update <folder-id> --name "New Name"
roboflow folder delete <folder-id>

Annotation batches and jobs

roboflow annotation batch list -p my-project
roboflow annotation batch get <batch-id> -p my-project
roboflow annotation batch admin-list -p my-project --limit 50
roboflow annotation batch images <batch-id> -p my-project
roboflow annotation batch create -p my-project --source-batch-id <batch-id> \
  --image-id <image-id> --name "Review batch"
roboflow annotation batch merge -p my-project --source-batch-id <source-id> \
  --target-batch-id <target-id> --yes

roboflow annotation job admin-list -p my-project --limit 50
roboflow annotation job admin-get <job-id> -p my-project
roboflow annotation job admin-create -p my-project --batch <batch-id> \
  --labeler a@co.com --reviewer b@co.com --name "Label round 1"
roboflow annotation job reassign-images -p my-project --image-id <image-id> \
  --labeler a@co.com --yes
roboflow annotation job create -p my-project --name "Label round 1" \
  --batch <batch-id> --num-images 100 --labeler a@co.com --reviewer b@co.com
roboflow annotation job images <job-id> -p my-project
roboflow annotation job submit-review <job-id> -p my-project
roboflow annotation job review-image <job-id> <image-id> -p my-project --status approved
roboflow annotation job return-edits <job-id> -p my-project --new-labeler a@co.com
roboflow annotation job accept <job-id> -p my-project --split-method split \
  --status approved --train-count 80 --valid-count 10 --test-count 10 --yes

Use admin-list --after <continuation-token> to fetch the next page. Commands that delete or consolidate resources, or accept images into Dataset, require --yes when run non-interactively. Run a batch or job subcommand with --help for the full administration surface.

The same operations are available from a Project in Python:

batches = project.get_annotation_batches(limit=50)
job = project.create_annotation_job_admin(
    batch_id="batch-id",
    labeler_email="labeler@example.com",
    reviewer_email="reviewer@example.com",
)
project.submit_annotation_job_for_review(job["id"])
project.accept_annotation_job_images(
    job["id"],
    split_method="split",
    statuses_to_include=["approved"],
    train_count=80,
    valid_count=10,
    test_count=10,
)

Auto-label a batch with a foundation model

roboflow autolabel models
roboflow autolabel preview -p my-project -m sam3-rle --image https://example.com/sample.jpg \
  --class cat --class dog
roboflow autolabel start -p my-project --batch-id <batch-id> -m gpt-6-astra-boxes \
  --ontology '{"a cat": "cat", "a dog": "dog"}' --confidence 0.5 --reviewer b@co.com
roboflow autolabel start -p my-project --batch-id <batch-id> -m my-project/3 --model-type roboflow
roboflow autolabel start -p my-project --batch-id <batch-id> -m sam3-rle --preserve-existing
roboflow autolabel job <job-id>
roboflow autolabel job <job-id> -p other-workspace/my-project

models lists the catalog for the workspace (id, availability, credits per image, default). preview runs one image through a model for free so you can compare candidates before spending credits. start creates the job and prints jobId and annotationJobId; poll it with job. Pass the ontology either as repeated --class flags or as --ontology JSON. The ontology is keyed by prompt, not by class: '{"kitten": "cat", "tabby": "cat"}' labels whatever matches either prompt as class cat. That direction is what lets several prompts share one output class. JSON options also accept a curl-style file reference (--ontology @ontology.json). --image accepts an HTTPS URL or a local file. By default a job replaces the annotations already on the batch images; --preserve-existing keeps them and only adds new ones. job looks the id up in your default workspace, so when the job was started with a workspace/project shorthand pass the same -p to job.

The same operations are available in Python:

models = workspace.autolabel_models()["models"]
preview = project.autolabel_preview("sam3-rle", "sample.jpg", ontology={"cat": "cat"})
job = project.autolabel("batch-id", model="gpt-6-astra-boxes", ontology={"a cat": "cat"})
project.autolabel_job(job["jobId"])["status"]

RFDM devices (v2 deployments)

Workspace-scoped device management — backed by the external Deployments API (/:workspace/devices/v2/*). Read commands need the device:read scope on your api_key; create needs device:update.

roboflow device list
roboflow device get <device-id>
roboflow device create "Factory floor cam" --type edge --tags floor-1,vision

# Observe — config is sensitive (may include credentials).
roboflow device config <device-id>
roboflow device config-history <device-id> --limit 20

# Streams the device runs.
roboflow device streams <device-id>
roboflow device stream <device-id> <stream-id>

# Logs (5 req/min/IP) and aggregated telemetry (60 req/min).
roboflow device logs <device-id> --severity ERROR --limit 200
roboflow device telemetry <device-id> --time-period 7d

# Lifecycle events (stream start/stop, errors, config changes…).
roboflow device events <device-id> --entity-type stream --direction backward

Workflows

roboflow workflow list
roboflow workflow get my-workflow
roboflow workflow create --name "My Workflow" --definition workflow.json
roboflow workflow update my-workflow --definition updated.json
roboflow workflow version list my-workflow
roboflow workflow fork other-ws/their-workflow

Fork a Universe project (async)

# Fork a public Universe project into the default (or --workspace) workspace.
# By default this blocks until the async task completes (up to --timeout seconds).
roboflow project fork https://universe.roboflow.com/leo-ueno-uduc7/license-plate-recognition
roboflow project fork leo-ueno-uduc7/license-plate-recognition --workspace my-ws

# Return immediately with a {taskId, url} payload instead of waiting.
roboflow project fork leo-ueno-uduc7/license-plate-recognition --no-wait

# Poll the resulting task later (works for any async task that returns a taskId).
roboflow asynctasks get  <task-id>
roboflow asynctasks wait <task-id> --timeout 600

Create a dataset version

roboflow version create -p my-project --settings settings.json

Delete and restore (soft delete / Trash)

# Move a project to Trash — any in-flight training jobs are cancelled automatically.
# Items stay in Trash for 30 days, then are permanently cleaned up.
roboflow project delete my-workspace/my-project
roboflow project restore my-workspace/my-project

# Same flow for versions (also cancels in-flight training on the version).
roboflow version delete my-workspace/my-project/3
roboflow version restore my-workspace/my-project/3

# Same flow for workflows.
roboflow workflow delete my-workflow
roboflow workflow restore my-workflow

# Inspect what's currently in Trash.
roboflow trash list

# Skip the confirmation prompt for scripts.
roboflow project delete my-workspace/my-project --yes

Permanent deletion (emptying Trash or skipping the retention window for a single item) is intentionally not available from the SDK or CLI — those actions destroy data irrecoverably and live only in the web UI's Trash view. Items left in Trash are cleaned up automatically after 30 days.

Inspect model evaluations

# List evals in the workspace; filter by project, version, model, or status.
roboflow eval list --status done --limit 10

# Read a single eval's metadata + summary metrics.
roboflow eval get <eval-id>

# Pull each panel — pipe to jq for structured access.
roboflow eval map-results <eval-id> --json | jq '.splits.test.map50'
roboflow eval performance-by-class <eval-id> --split test
roboflow eval confusion-matrix <eval-id> --split test --confidence 30
roboflow eval confidence-sweep <eval-id> --json
roboflow eval vector-analysis <eval-id> --confidence 20 --json
roboflow eval image-predictions <eval-id> --split test --limit 200
roboflow eval recommendations <eval-id> --json

Exit codes are stable per error class so scripts and agents can react without parsing message strings: 2 for authentication or access errors (401/403), 3 for model_eval_not_found (404), 4 for model_eval_not_done (409 — eval still running), 5 for invalid_split / invalid_confidence (400). Requires the model-eval:read scope on the api key.

Compare Models

# Compare accuracy and latency for one version.
roboflow --workspace my-workspace eval compare --project my-project --version 3

# Choose the Pareto frontier metric; return all metrics and exclusion reasons.
roboflow eval compare --project my-project --version 3 --frontier-metric mAP5095 --json

Reads existing evaluations; does not start new ones. Requires model-eval:read and workspace Model Evaluation access.

Evaluate Workflows (Workflow Evals)

# Discover the engine catalog and what your key may do.
roboflow workflow-eval capabilities --json
roboflow workflow-eval evaluator list
roboflow workflow-eval schema get spec --json

# Author: Spec, Eval Dataset, Cases, Eval.
roboflow workflow-eval spec create --body @spec.json --name "Boolean answer"
roboflow workflow-eval dataset create --body @dataset.json
roboflow workflow-eval case upload ./image.png --dataset <dataset-id>   # prints artifactId
roboflow workflow-eval case add --dataset <dataset-id> --body @case.json
roboflow workflow-eval case import --dataset <dataset-id> --input-field image --from-dataset my-project:valid
roboflow workflow-eval create --name "Answer accuracy" --spec <spec-id> --dataset <dataset-id>

# Bind a Workflow, run it, and read results.
roboflow workflow-eval binding suggest --spec <spec-id> --dataset <dataset-id> --workflow <workflow-id> --json
roboflow workflow-eval run start --eval <eval-id> --body @run.json --wait
roboflow workflow-eval execution overview <execution-id> --eval <eval-id> --run <run-id> --json
roboflow workflow-eval execution results <execution-id> --eval <eval-id> --run <run-id> --failed-check
roboflow workflow-eval compare --eval <eval-id> -x <execution-a> -x <execution-b> --json
roboflow workflow-eval export start --eval <eval-id> --run <run-id> --format csv --wait

# Agent guidance served by the installed engine.
roboflow workflow-eval agent manifest --json
roboflow workflow-eval agent skill skill:create-eval

--body accepts inline JSON, @file.json, a file path, or - for stdin. Commands that create resources or start work send a fresh Idempotency-Key (override with --idempotency-key to retry safely); updates take the resource's current --revision. Deleting an Eval or Run shows its impact and asks for confirmation (--yes to skip). Requires the Workflow Evals feature and the workflow-evals:read|write|run|export scopes; running saved Workflows also needs workflow:read and model:infer. The same API is available in Python via rf.workspace().workflow_evals().

Workspace stats and billing

roboflow workspace usage
roboflow workspace plan
roboflow workspace stats --start-date 2026-01-01 --end-date 2026-03-31

Search Roboflow Universe

roboflow universe search "hard hats" --type dataset --limit 5

Video inference

roboflow video infer -p my-project -v 3 -f video.mp4 --fps 10
roboflow video status <job-id>

Shell completion

The fastest path: let the CLI install completion for you. Auto-detects your shell from $SHELL.

roboflow completion install

This writes the completion script to a per-user location and updates your shell rc file (~/.bashrc or ~/.zshrc) so completion works in new shells. Idempotent — safe to re-run. Delegates to typer.completion.install under the hood.

Supported shells: bash, zsh, fish. Windows / PowerShell is not supported.

Override detection or scope to one shell:

roboflow completion install --shell zsh
roboflow completion install --shell bash
roboflow completion install --shell fish

Hidden commands (legacy aliases, snake_case shims, not-yet-implemented stubs) are filtered from completion automatically.

To uninstall, delete the completion script (location depends on your shell — typer writes to ~/.bash_completions/roboflow.sh, ~/.zfunc/_roboflow, or ~/.config/fish/completions/roboflow.fish) and remove any source ... line typer added to your ~/.bashrc.

Advanced: print the script yourself

If you want full control, generate the raw script and source it however you like:

# Zsh
eval "$(roboflow completion zsh)"

# Bash (requires bash >= 4.4)
eval "$(roboflow completion bash)"

# Fish
roboflow completion fish | source

JSON output for agents

Every command supports --json for structured output that's safe to pipe:

# stdout: JSON data, stderr: JSON errors, exit codes: 0/1/2/3
roboflow --json project list | python3 -c "import sys,json; print(json.load(sys.stdin))"
roboflow --json project get nonexistent 2>/dev/null   # stderr gets the error JSON

Error schema is consistent: {"error": {"message": "...", "hint": "..."}}

Resource shorthand

Resources can be addressed with compact identifiers:

Shorthand	Resolves to
`my-project`	default workspace + project
`my-ws/my-project`	explicit workspace + project
`my-project/3`	default workspace + project + version 3
`my-ws/my-project/3`	explicit workspace + project + version 3

Version numbers are always numeric — that's how x/y is disambiguated between workspace/project and project/version.

All command groups

Command	Description
`auth`	Login, logout, status, set region or default workspace
`api-key`	List, create, update, protect, disable, revoke workspace API keys
`workspace`	List and inspect workspaces
`project`	List, get, create projects
`version`	List, get, download, export dataset versions
`image`	Upload, get, search, metadata, tag, delete, annotate images and videos
`model`	List, get, upload trained models
`train`	Start model training
`infer`	Run inference on images
`search`	Search workspace images and videos (RoboQL), export results
`deployment`	Manage dedicated deployments
`device`	List, get, create, and observe RFDM devices (v2 deployment API)
`eval`	Inspect model evaluation runs (mAP, confusion matrix, recommendations, ...)
`workflow`	Manage workflows
`workflow-eval`	Evaluate Workflows: Specs, Eval Datasets, Cases, Runs, results, exports
`folder`	Manage workspace folders
`annotation`	Annotation batches and jobs
`autolabel`	Auto-label batches with hosted foundation or Roboflow models
`asynctasks`	Inspect async background tasks (e.g. project forks)
`trash`	List items in Trash
`universe`	Search Roboflow Universe
`video`	Video inference
`batch`	Batch processing jobs (coming soon)
`completion`	Install or generate shell completion scripts (bash, zsh, fish)

Run roboflow <command> --help for details on any command.

Backwards compatibility

All legacy command names still work:

Legacy	Current
`roboflow login`	`roboflow auth login`
`roboflow whoami`	`roboflow auth status`
`roboflow upload <file>`	`roboflow image upload <file>`
`roboflow import <dir>`	`roboflow image upload <dir>`
`roboflow download <url>`	`roboflow version download <url>`
`roboflow search-export`	`roboflow search --export`
`roboflow train`	`roboflow train start`
`roboflow deployment add`	`roboflow deployment create`
`roboflow deployment machine_type`	`roboflow deployment machine-type`

Navigation Menu

Repository navigation

Roboflow CLI

Install & authenticate

Select a Roboflow region

Global flags

Quick examples

Create a project and upload images

Download a dataset

Run inference

Batch Process Asset Library images

Train, monitor, cancel, stop

Train recipes — custom hyperparameters & augmentation (v2)

NAS models — list, star, deploy

Update image metadata and tags

Search and export

Browse resources

Manage folders

Annotation batches and jobs

Auto-label a batch with a foundation model

RFDM devices (v2 deployments)

Workflows

Fork a Universe project (async)

Create a dataset version

Delete and restore (soft delete / Trash)

Inspect model evaluations

Compare Models

Evaluate Workflows (Workflow Evals)

Workspace stats and billing

Search Roboflow Universe

Video inference

Shell completion

Advanced: print the script yourself

JSON output for agents

Resource shorthand

All command groups

Backwards compatibility

FilesExpand file tree

CLI-COMMANDS.md

Latest commit

History

CLI-COMMANDS.md

File metadata and controls

Roboflow CLI

Install & authenticate

Select a Roboflow region

Global flags

Quick examples

Create a project and upload images

Download a dataset

Run inference

Batch Process Asset Library images

Train, monitor, cancel, stop

Train recipes — custom hyperparameters & augmentation (v2)

NAS models — list, star, deploy

Update image metadata and tags

Search and export

Browse resources

Manage folders

Annotation batches and jobs

Auto-label a batch with a foundation model

RFDM devices (v2 deployments)

Workflows

Fork a Universe project (async)

Create a dataset version

Delete and restore (soft delete / Trash)

Inspect model evaluations

Compare Models

Evaluate Workflows (Workflow Evals)

Workspace stats and billing

Search Roboflow Universe

Video inference

Shell completion

Advanced: print the script yourself

JSON output for agents

Resource shorthand

All command groups

Backwards compatibility