# Using the CLI

The Roboflow Python package includes a CLI (`pip install roboflow`) that you can use to work with the Roboflow platform from the command line. It follows a consistent `roboflow <noun> <verb>` pattern and supports structured JSON output for use with AI coding agents and automation tools.

## Commands

| Command      | Description                                           |
| ------------ | ----------------------------------------------------- |
| `auth`       | Login, logout, check status, set default workspace    |
| `workspace`  | List and inspect workspaces                           |
| `project`    | List, get, and create projects                        |
| `version`    | List, get, download, and export dataset versions      |
| `image`      | Upload, get, search, tag, delete, and annotate images |
| `model`      | List, get, and upload trained models                  |
| `train`      | Start model training                                  |
| `infer`      | Run inference on an image                             |
| `search`     | Search workspace images and export results            |
| `deployment` | Manage dedicated deployments                          |
| `workflow`   | Manage workflows                                      |
| `folder`     | Manage workspace folders                              |
| `annotation` | Annotation batches and jobs                           |
| `universe`   | Search Roboflow Universe                              |
| `video`      | Video inference                                       |
| `batch`      | Batch processing jobs *(coming soon)*                 |
| `completion` | Generate shell completion scripts (bash, zsh, fish)   |

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

## Global Flags

These flags work on every command and can appear before or after the subcommand:

| Flag          | Short | Description                                               |
| ------------- | ----- | --------------------------------------------------------- |
| `--json`      | `-j`  | Output results as structured JSON (for agents and piping) |
| `--api-key`   | `-k`  | API key override                                          |
| `--workspace` | `-w`  | Workspace override                                        |
| `--quiet`     | `-q`  | Suppress progress bars and status messages                |
| `--version`   |       | Show package version                                      |

## JSON Output for Agents

Every command supports `--json` for structured output that's safe to pipe and parse programmatically:

```bash
roboflow --json project list | jq '.[0].id'
```

Errors in JSON mode go to stderr with an empty stdout, making it safe for piping:

```bash
roboflow --json project get nonexistent 2>error.json
# stdout is empty, stderr contains: {"error": {"message": "...", "hint": "..."}}
```

Exit codes are consistent: 0 = success, 1 = error, 2 = auth error, 3 = not found.

## Resource Shorthand

Resources can be addressed with compact identifiers:

| Shorthand            | Meaning                       |
| -------------------- | ----------------------------- |
| `my-project`         | Uses your default workspace   |
| `my-ws/my-project`   | Explicit workspace            |
| `my-project/3`       | Default workspace, version 3  |
| `my-ws/my-project/3` | Explicit workspace, version 3 |

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

## Convenience Aliases

Common operations have short top-level aliases:

| Alias               | Equivalent                  |
| ------------------- | --------------------------- |
| `roboflow login`    | `roboflow auth login`       |
| `roboflow whoami`   | `roboflow auth status`      |
| `roboflow upload`   | `roboflow image upload`     |
| `roboflow download` | `roboflow version download` |