# 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` |


---

# 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/command-line-interface/using-the-cli.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.