Choosing the Right Tool

When to use the CLI, Python SDK, or REST API.

Roboflow exposes the same underlying platform through three developer tools. They are not mutually exclusive - most production workflows use all three. This page is a quick decision guide.

At a glance

	CLI	Python SDK	REST API
Best for	Ad-hoc scripts, AI agents, shell automation	Notebooks, scheduled jobs, Python applications	Non-Python services, webhooks, edge devices
Auth	ROBOFLOW_API_KEY env var or roboflow login	API key passed to Roboflow(...) or ROBOFLOW_API_KEY	api_key= query param or body field
Output	Pretty tables by default, --json for scripting	Python dicts and objects	JSON
Install	pip install roboflow	pip install roboflow	None
Coverage	Tracks SDK; agent-friendly	Same as REST plus convenience helpers	Authoritative - every feature ships here first
Errors	Exit codes (0 / 1 / 2 / 3) + JSON error body on stderr	Python exceptions	HTTP status codes + JSON error body

When to use the CLI

Use the CLI when you want to do something once or as a step in a shell pipeline. The output formats and exit codes are designed for scripting and AI agents.

Concretely:

• You're prototyping and want to see results quickly without writing Python.

• You want to pipe Roboflow operations into other tools (roboflow project list --json | jq …).

• You're using an AI coding agent (Claude Code, Cursor) - the CLI's structured JSON output and stable exit codes are easier for an agent to consume than a Python REPL.

• You're writing a Makefile, GitHub Action, or shell script that uploads images, kicks off training, or downloads a dataset.

See Using the CLI.

When to use the Python SDK

Use the SDK when you're already in Python and want typed objects, idiomatic helpers, and cross-call state. The SDK is a thin wrapper around the REST API but it adds:

• Workspace / Project / Version / Model objects with discoverable methods.

• Concurrent uploads (upload_dataset(num_workers=10)).

• Prediction visualization helpers (when the full roboflow package is installed - not roboflow-slim).

• Active-learning loops that combine inference and upload.

• Direct access to vision-events ingestion.

Concretely:

• You're in a Jupyter notebook iterating on a dataset.

• You're building a Python service that uploads, trains, or runs inference on demand.

• You need to chain operations (upload → train → wait for ready → predict).

• You're integrating Roboflow into an existing Python app.

See Using the Python SDK.

When to use the REST API

Use the REST API when you're not in Python, when you need to call from an environment that can't install Python packages (a browser, a Cloudflare Worker, an embedded device, a Lambda with a tiny zipfile), or when you want to consume Roboflow from a webhook.

Concretely:

• You're building a JavaScript / TypeScript / Go / Rust client.

• You're posting events from a webcam or sensor that runs custom firmware.

• You need to integrate with Zapier / n8n / a no-code automation tool.

• A specific feature ships in the REST API before it lands in the SDK.

See Using the REST API.

Mixing tools

In practice teams use all three:

• CI/CD uses the CLI to upload datasets and kick off training.

• A Python data pipeline uses the SDK to react to training results and tune model versions.

• A production app uses the REST API to run inference and post events.

The same workspace and API key authenticate against all three, so credentials don't multiply.

Inference is special

For running a trained model on an image or video, you have additional choices beyond these three. Hosted inference runs against Roboflow Serverless v2 at serverless.roboflow.com; for higher throughput or on-prem use cases see Roboflow Inference (self-hosted) and Dedicated Deployments (managed GPU machines).

The CLI's infer command, the SDK's model.predict(), and a direct REST call to the inference URL are all paths to the same underlying inference engines.