# Choosing the Right Tool

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](/developer/command-line-interface/using-the-cli.md).

## 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](/developer/python-sdk/using-the-python-sdk.md).

## 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](/developer/rest-api/using-the-rest-api.md).

## 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](https://docs.roboflow.com/deploy/serverless) at `serverless.roboflow.com`; for higher throughput or on-prem use cases see [Roboflow Inference](https://inference.roboflow.com) (self-hosted) and [Dedicated Deployments](https://docs.roboflow.com/deploy/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/choosing-the-right-tool.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.