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 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/Modelobjects with discoverable methods.- Concurrent uploads (
upload_dataset(num_workers=10)). - Prediction visualization helpers (when the full
roboflowpackage is installed - notroboflow-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 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 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 the Roboflow Serverless Hosted API 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.