cloudinary-cli 1.14.1__tar.gz → 1.16.0__tar.gz

{cloudinary_cli-1.14.1/cloudinary_cli.egg-info → cloudinary_cli-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloudinary-cli
-Version: 1.14.1
+Version: 1.16.0
 Summary: A command line interface for Cloudinary with full API support
 Home-page: https://github.com/cloudinary/cloudinary-cli
 Author: Cloudinary, Brian Luk
@@ -10,14 +10,15 @@ Keywords: cloudinary cli pycloudinary image video digital asset management comma
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6.0
+Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cloudinary>=1.42.2
+Requires-Dist: cloudinary>=1.45.0
 Requires-Dist: pygments
 Requires-Dist: jinja2
 Requires-Dist: click
 Requires-Dist: click-log
+Requires-Dist: filelock
 Requires-Dist: requests
 Requires-Dist: docstring-parser
 Requires-Dist: urllib3>=2.2.2
@@ -37,28 +38,118 @@ It is fully documented at [https://cloudinary.com/documentation/cloudinary_cli](
 ## Requirements
 Your own Cloudinary account.  If you don't already have one, sign up at [https://cloudinary.com/users/register/free](https://cloudinary.com/users/register/free).
 
-Python 3.6 or later.  You can install Python from [https://www.python.org/](https://www.python.org/). Note that the Python Package Installer (pip) is installed with it.
+Python 3.8 or later.  You can install Python from [https://www.python.org/](https://www.python.org/). Note that the Python Package Installer (pip) is installed with it.
 
-## Setup and Installation
+## Installation
 
-1. To install this package, run: `pip3 install cloudinary-cli`
-2. To make all your `cld` commands point to your Cloudinary account, set up your CLOUDINARY\_URL environment variable. For example:
-    * On Mac or Linux:<br>`export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
-    * On Windows (cmd.exe):<br>`set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
-    * On Windows (PowerShell):<br>`$Env:CLOUDINARY_URL="cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name"`
+The CLI is published on PyPI as [`cloudinary-cli`](https://pypi.org/project/cloudinary-cli/). The package name (`cloudinary-cli`) is what you install; the command it provides is **`cld`** (it also installs a `cloudinary` alias). Pick the method that fits your setup. If you just want a working `cld` command and aren't sure, use **pipx** or **uv** — they install the CLI in its own isolated environment, so it won't conflict with other Python packages and you don't need to manage a virtual environment yourself.
+
+### Option 1 — pipx (recommended)
+
+[pipx](https://pipx.pypa.io) installs Python CLI tools into isolated environments and puts the `cld` command on your `PATH` automatically.
+
+```sh
+# Install pipx if you don't have it:
+#   macOS:           brew install pipx && pipx ensurepath
+#   Debian/Ubuntu:   sudo apt install pipx && pipx ensurepath
+#   Any platform:    python3 -m pip install --user pipx && python3 -m pipx ensurepath
+
+pipx install cloudinary-cli
+
+# Upgrade later with:
+pipx upgrade cloudinary-cli
+```
+
+After `pipx ensurepath`, open a new terminal so the updated `PATH` takes effect.
+
+### Option 2 — uv
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package manager. Its `uv tool` command installs CLIs in isolation, like pipx:
+
+```sh
+uv tool install cloudinary-cli
+
+# Upgrade later with:
+uv tool upgrade cloudinary-cli
+```
+
+Or run it once without installing. The package's command is `cld`, so name it with `--from`:
+
+```sh
+uvx --from cloudinary-cli cld --help    # uvx is shorthand for `uv tool run`
+```
+
+### Option 3 — pip
+
+A plain `pip` install also works. Prefer a virtual environment so the CLI and its dependencies don't collide with your system or other projects:
+
+```sh
+python3 -m venv ~/.venvs/cloudinary-cli
+source ~/.venvs/cloudinary-cli/bin/activate    # Windows: .\.venvs\cloudinary-cli\Scripts\activate
+pip install cloudinary-cli
+```
+
+To install without a virtual environment, use a per-user install (avoids needing `sudo` and keeps it out of system Python):
+
+```sh
+python3 -m pip install --user cloudinary-cli
+```
+
+If `cld` is not found afterwards, the user scripts directory is not on your `PATH`. See [Troubleshooting](#troubleshooting-the-cld-command).
+
+### Option 4 — Docker (no Python needed)
+
+If you'd rather not install Python at all, run the CLI from the official Docker image. See [Docker Usage](#docker-usage) below.
+
+### Verify the installation
+
+```sh
+cld --version
+```
+
+### Troubleshooting the `cld` command
+
+If your shell reports `cld: command not found` after installing:
+
+- **pipx / uv:** run `pipx ensurepath` (or `uv tool update-shell`), then open a new terminal.
+- **pip `--user` install:** the user scripts directory is not on your `PATH`. Find it with `python3 -m site --user-base` (the scripts live in its `bin` subdirectory on macOS/Linux, or `Scripts` on Windows) and add that to your `PATH`. For example, on macOS/Linux add this to `~/.zshrc` or `~/.bash_profile`:
+
+  ```sh
+  export PATH="$PATH:$(python3 -m site --user-base)/bin"
+  ```
+
+- As a fallback, you can always invoke the CLI through Python: `python3 -m cloudinary_cli.cli <command>`.
+
+## Configuration
+
+Once installed, point your `cld` commands at a Cloudinary account using **either** of the following.
+
+**Option A — Log in with OAuth (recommended).** Run:
+
+```sh
+cld login
+```
+
+This opens your browser to authorize the CLI, then saves the login as a configuration (named after the cloud) and sets it as the default. The CLI refreshes the token automatically, and you can remove the login at any time with `cld logout`.
+
+**Option B — Set your `CLOUDINARY_URL` environment variable.** For example:
+
+* On Mac or Linux:<br>`export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
+* On Windows (cmd.exe):<br>`set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
+* On Windows (PowerShell):<br>`$Env:CLOUDINARY_URL="cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name"`
 
 _**Note:** you can copy and paste your account environment variable from the Account Details section of the Dashboard page in the Cloudinary console._
 
-3. Check your configuration by running `cld config`. A response of the following form is returned:
+Then check your configuration by running `cld config`. A response of the following form is returned:
 
-    ```
-    cloud_name:     <CLOUD_NAME>
-    api_key:        <API_KEY>
-    api_secret:     ***************<LAST_4_DIGITS>
-    private_cdn:    <True|False>
-    ```
+```
+cloud_name:     <CLOUD_NAME>
+api_key:        <API_KEY>
+api_secret:     ***************<LAST_4_DIGITS>
+private_cdn:    <True|False>
+```
 
-    If you get an error message when running `cld config`, you may need to add your Python installation to your $PATH. To do so, you can run `PATH="$PATH:/Library/Python/Versions/3.8/bin"` in your terminal, and add `export PATH="$PATH:/Library/Python/Versions/3.8/bin"` to your `/.bash_profile` or `~/.zshrc`.
+If `cld` itself is not found, see [Troubleshooting the `cld` command](#troubleshooting-the-cld-command).
 
 ## Quickstart
 
@@ -72,9 +163,12 @@ Usage: cld [cli options] [command] [command options] [method] [method parameters
 
 ```
 cld --help         # Lists available commands.
+cld login          # Logs in to a Cloudinary account via OAuth in your browser.
+cld logout         # Revokes and removes a saved OAuth login.
 cld search --help  # Shows usage for the Search API.
 cld admin          # Lists Admin API methods.
 cld uploader       # Lists Upload API methods.
+cld agent signup   # For AI agents: creates a Cloudinary account on behalf of a human.
 ```
 
 ## Docker Usage
@@ -248,6 +342,28 @@ cld [cli options] migrate [command options] upload_mapping file
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#migrate).
 
+### `agent signup`
+
+**For AI agents only.** Creates a Free-plan Cloudinary account on behalf of a human. No existing configuration is required to run it. A verification email is sent to the address, and the returned credentials are **inert until the human completes that verification**. The new product environment is saved as a named configuration (named after the cloud) so it is ready to use once activated.
+
+```
+cld agent signup [command options] <email> <agent_framework> <agent_llm_model> <agent_goal>
+```
+
+Example:
+
+```
+cld agent signup you@example.com claude-code claude-fable-5 "test the agent account flow"
+```
+
+Options:
+
+* `--name <name>` — name for the saved configuration (default: the returned cloud name).
+* `--set-default` — set the saved configuration as the default.
+* `--no-save` — show the credentials but do not save them as a configuration.
+* `--sdk-framework <name>` — the Cloudinary SDK framework the agent intends to use.
+* `--json` — output the full raw JSON response (the agent contract) instead of the human-readable summary.
+
 ## Additional configurations
 
 A configuration is a reference to a specified Cloudinary account or cloud name via its environment variable.  You set the default configuration during setup and installation. Using different configurations allows you to access different Cloudinary cloud names, such as sub-accounts of your main Cloudinary account, or any additional Cloudinary accounts you may have.
@@ -268,7 +384,7 @@ Whereas using the saved configuration "accountx":
 cld -C accountx admin usage
 ```
 
-_**Caution:** Creating a saved configuration may put your API secret at risk as it is stored in a local plain text file._
+_**Caution:** Creating a saved configuration may put your credentials at risk as they are stored in a local plain text file. This applies to both API-key configurations and OAuth logins._
 
 You can create, delete and list saved configurations using the `config` command.
 
@@ -277,3 +393,42 @@ cld config [options]
 ```
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#config).
+
+### Logging in with OAuth
+
+Instead of saving an API key and secret, you can log in to a Cloudinary account through your browser. The CLI saves the resulting session as a named configuration and refreshes its token automatically.
+
+```
+cld login                  # Log in and save the configuration (named after the cloud).
+cld login my-account       # Save the login under a specific name.
+cld logout                 # Choose a saved OAuth login to log out of.
+cld logout my-account      # Log out of a specific saved OAuth login.
+```
+
+The first login becomes the default automatically. When other configurations already exist, the new login is saved but not made the default; `cld login` tells you so and prints the command to make it the default. Once saved, an OAuth login is selected with `-C <name>` just like any other saved configuration.
+
+`cld logout` revokes the login's token at the server and removes the saved configuration. If the token cannot be revoked (for example, you are offline), the saved configuration is still removed.
+
+### Choosing a default configuration
+
+The default configuration is used when no `-c`/`-C` option is given and no `CLOUDINARY_URL` environment variable is set. The first OAuth login becomes the default automatically; you can change it at any time.
+
+```
+cld config -d <name>           # Set an existing saved configuration as the default.
+cld config --unset-default     # Clear the stored default.
+cld config -ls                 # List saved configurations, marking the default and the active one.
+```
+
+When creating a configuration with `-n` or `--from_url`, add `--set-default` to make it the default in the same step. Resolution precedence is: `-c` (inline URL) > `-C` (saved name) > stored default > `CLOUDINARY_URL` environment variable.
+
+### Refreshing OAuth tokens
+
+OAuth tokens are refreshed automatically as needed, but you can refresh them manually.
+
+```
+cld config --refresh <name>    # Refresh a saved OAuth configuration's token.
+cld config --refresh-all       # Refresh every saved OAuth configuration whose token is stale.
+cld config --refresh <name> --force   # Refresh even if the token is still fresh.
+```
+
+If a token can no longer be refreshed (for example, the login was revoked), the CLI reports the configuration and the `cld login` command to use to log in again.

{cloudinary_cli-1.14.1 → cloudinary_cli-1.16.0}/README.md

@@ -12,28 +12,118 @@ It is fully documented at [https://cloudinary.com/documentation/cloudinary_cli](
 ## Requirements
 Your own Cloudinary account.  If you don't already have one, sign up at [https://cloudinary.com/users/register/free](https://cloudinary.com/users/register/free).
 
-Python 3.6 or later.  You can install Python from [https://www.python.org/](https://www.python.org/). Note that the Python Package Installer (pip) is installed with it.
+Python 3.8 or later.  You can install Python from [https://www.python.org/](https://www.python.org/). Note that the Python Package Installer (pip) is installed with it.
 
-## Setup and Installation
+## Installation
 
-1. To install this package, run: `pip3 install cloudinary-cli`
-2. To make all your `cld` commands point to your Cloudinary account, set up your CLOUDINARY\_URL environment variable. For example:
-    * On Mac or Linux:<br>`export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
-    * On Windows (cmd.exe):<br>`set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
-    * On Windows (PowerShell):<br>`$Env:CLOUDINARY_URL="cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name"`
+The CLI is published on PyPI as [`cloudinary-cli`](https://pypi.org/project/cloudinary-cli/). The package name (`cloudinary-cli`) is what you install; the command it provides is **`cld`** (it also installs a `cloudinary` alias). Pick the method that fits your setup. If you just want a working `cld` command and aren't sure, use **pipx** or **uv** — they install the CLI in its own isolated environment, so it won't conflict with other Python packages and you don't need to manage a virtual environment yourself.
+
+### Option 1 — pipx (recommended)
+
+[pipx](https://pipx.pypa.io) installs Python CLI tools into isolated environments and puts the `cld` command on your `PATH` automatically.
+
+```sh
+# Install pipx if you don't have it:
+#   macOS:           brew install pipx && pipx ensurepath
+#   Debian/Ubuntu:   sudo apt install pipx && pipx ensurepath
+#   Any platform:    python3 -m pip install --user pipx && python3 -m pipx ensurepath
+
+pipx install cloudinary-cli
+
+# Upgrade later with:
+pipx upgrade cloudinary-cli
+```
+
+After `pipx ensurepath`, open a new terminal so the updated `PATH` takes effect.
+
+### Option 2 — uv
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package manager. Its `uv tool` command installs CLIs in isolation, like pipx:
+
+```sh
+uv tool install cloudinary-cli
+
+# Upgrade later with:
+uv tool upgrade cloudinary-cli
+```
+
+Or run it once without installing. The package's command is `cld`, so name it with `--from`:
+
+```sh
+uvx --from cloudinary-cli cld --help    # uvx is shorthand for `uv tool run`
+```
+
+### Option 3 — pip
+
+A plain `pip` install also works. Prefer a virtual environment so the CLI and its dependencies don't collide with your system or other projects:
+
+```sh
+python3 -m venv ~/.venvs/cloudinary-cli
+source ~/.venvs/cloudinary-cli/bin/activate    # Windows: .\.venvs\cloudinary-cli\Scripts\activate
+pip install cloudinary-cli
+```
+
+To install without a virtual environment, use a per-user install (avoids needing `sudo` and keeps it out of system Python):
+
+```sh
+python3 -m pip install --user cloudinary-cli
+```
+
+If `cld` is not found afterwards, the user scripts directory is not on your `PATH`. See [Troubleshooting](#troubleshooting-the-cld-command).
+
+### Option 4 — Docker (no Python needed)
+
+If you'd rather not install Python at all, run the CLI from the official Docker image. See [Docker Usage](#docker-usage) below.
+
+### Verify the installation
+
+```sh
+cld --version
+```
+
+### Troubleshooting the `cld` command
+
+If your shell reports `cld: command not found` after installing:
+
+- **pipx / uv:** run `pipx ensurepath` (or `uv tool update-shell`), then open a new terminal.
+- **pip `--user` install:** the user scripts directory is not on your `PATH`. Find it with `python3 -m site --user-base` (the scripts live in its `bin` subdirectory on macOS/Linux, or `Scripts` on Windows) and add that to your `PATH`. For example, on macOS/Linux add this to `~/.zshrc` or `~/.bash_profile`:
+
+  ```sh
+  export PATH="$PATH:$(python3 -m site --user-base)/bin"
+  ```
+
+- As a fallback, you can always invoke the CLI through Python: `python3 -m cloudinary_cli.cli <command>`.
+
+## Configuration
+
+Once installed, point your `cld` commands at a Cloudinary account using **either** of the following.
+
+**Option A — Log in with OAuth (recommended).** Run:
+
+```sh
+cld login
+```
+
+This opens your browser to authorize the CLI, then saves the login as a configuration (named after the cloud) and sets it as the default. The CLI refreshes the token automatically, and you can remove the login at any time with `cld logout`.
+
+**Option B — Set your `CLOUDINARY_URL` environment variable.** For example:
+
+* On Mac or Linux:<br>`export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
+* On Windows (cmd.exe):<br>`set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
+* On Windows (PowerShell):<br>`$Env:CLOUDINARY_URL="cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name"`
 
 _**Note:** you can copy and paste your account environment variable from the Account Details section of the Dashboard page in the Cloudinary console._
 
-3. Check your configuration by running `cld config`. A response of the following form is returned:
+Then check your configuration by running `cld config`. A response of the following form is returned:
 
-    ```
-    cloud_name:     <CLOUD_NAME>
-    api_key:        <API_KEY>
-    api_secret:     ***************<LAST_4_DIGITS>
-    private_cdn:    <True|False>
-    ```
+```
+cloud_name:     <CLOUD_NAME>
+api_key:        <API_KEY>
+api_secret:     ***************<LAST_4_DIGITS>
+private_cdn:    <True|False>
+```
 
-    If you get an error message when running `cld config`, you may need to add your Python installation to your $PATH. To do so, you can run `PATH="$PATH:/Library/Python/Versions/3.8/bin"` in your terminal, and add `export PATH="$PATH:/Library/Python/Versions/3.8/bin"` to your `/.bash_profile` or `~/.zshrc`.
+If `cld` itself is not found, see [Troubleshooting the `cld` command](#troubleshooting-the-cld-command).
 
 ## Quickstart
 
@@ -47,9 +137,12 @@ Usage: cld [cli options] [command] [command options] [method] [method parameters
 
 ```
 cld --help         # Lists available commands.
+cld login          # Logs in to a Cloudinary account via OAuth in your browser.
+cld logout         # Revokes and removes a saved OAuth login.
 cld search --help  # Shows usage for the Search API.
 cld admin          # Lists Admin API methods.
 cld uploader       # Lists Upload API methods.
+cld agent signup   # For AI agents: creates a Cloudinary account on behalf of a human.
 ```
 
 ## Docker Usage
@@ -223,6 +316,28 @@ cld [cli options] migrate [command options] upload_mapping file
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#migrate).
 
+### `agent signup`
+
+**For AI agents only.** Creates a Free-plan Cloudinary account on behalf of a human. No existing configuration is required to run it. A verification email is sent to the address, and the returned credentials are **inert until the human completes that verification**. The new product environment is saved as a named configuration (named after the cloud) so it is ready to use once activated.
+
+```
+cld agent signup [command options] <email> <agent_framework> <agent_llm_model> <agent_goal>
+```
+
+Example:
+
+```
+cld agent signup you@example.com claude-code claude-fable-5 "test the agent account flow"
+```
+
+Options:
+
+* `--name <name>` — name for the saved configuration (default: the returned cloud name).
+* `--set-default` — set the saved configuration as the default.
+* `--no-save` — show the credentials but do not save them as a configuration.
+* `--sdk-framework <name>` — the Cloudinary SDK framework the agent intends to use.
+* `--json` — output the full raw JSON response (the agent contract) instead of the human-readable summary.
+
 ## Additional configurations
 
 A configuration is a reference to a specified Cloudinary account or cloud name via its environment variable.  You set the default configuration during setup and installation. Using different configurations allows you to access different Cloudinary cloud names, such as sub-accounts of your main Cloudinary account, or any additional Cloudinary accounts you may have.
@@ -243,7 +358,7 @@ Whereas using the saved configuration "accountx":
 cld -C accountx admin usage
 ```
 
-_**Caution:** Creating a saved configuration may put your API secret at risk as it is stored in a local plain text file._
+_**Caution:** Creating a saved configuration may put your credentials at risk as they are stored in a local plain text file. This applies to both API-key configurations and OAuth logins._
 
 You can create, delete and list saved configurations using the `config` command.
 
@@ -252,3 +367,42 @@ cld config [options]
 ```
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#config).
+
+### Logging in with OAuth
+
+Instead of saving an API key and secret, you can log in to a Cloudinary account through your browser. The CLI saves the resulting session as a named configuration and refreshes its token automatically.
+
+```
+cld login                  # Log in and save the configuration (named after the cloud).
+cld login my-account       # Save the login under a specific name.
+cld logout                 # Choose a saved OAuth login to log out of.
+cld logout my-account      # Log out of a specific saved OAuth login.
+```
+
+The first login becomes the default automatically. When other configurations already exist, the new login is saved but not made the default; `cld login` tells you so and prints the command to make it the default. Once saved, an OAuth login is selected with `-C <name>` just like any other saved configuration.
+
+`cld logout` revokes the login's token at the server and removes the saved configuration. If the token cannot be revoked (for example, you are offline), the saved configuration is still removed.
+
+### Choosing a default configuration
+
+The default configuration is used when no `-c`/`-C` option is given and no `CLOUDINARY_URL` environment variable is set. The first OAuth login becomes the default automatically; you can change it at any time.
+
+```
+cld config -d <name>           # Set an existing saved configuration as the default.
+cld config --unset-default     # Clear the stored default.
+cld config -ls                 # List saved configurations, marking the default and the active one.
+```
+
+When creating a configuration with `-n` or `--from_url`, add `--set-default` to make it the default in the same step. Resolution precedence is: `-c` (inline URL) > `-C` (saved name) > stored default > `CLOUDINARY_URL` environment variable.
+
+### Refreshing OAuth tokens
+
+OAuth tokens are refreshed automatically as needed, but you can refresh them manually.
+
+```
+cld config --refresh <name>    # Refresh a saved OAuth configuration's token.
+cld config --refresh-all       # Refresh every saved OAuth configuration whose token is stale.
+cld config --refresh <name> --force   # Refresh even if the token is still fresh.
+```
+
+If a token can no longer be refreshed (for example, the login was revoked), the CLI reports the configuration and the `cld login` command to use to log in again.

cloudinary_cli-1.16.0/cloudinary_cli/auth/__init__.py

@@ -0,0 +1,143 @@
+"""OAuth login façade: runs the PKCE loopback flow and persists each login as a named
+`cloudinary://` entry in `config.json`. Token refresh lives in `auth.refresh`, re-exported here."""
+import secrets
+import webbrowser
+
+import requests
+
+from cloudinary_cli.auth import flow
+from cloudinary_cli.auth.loopback_server import start_callback_server, wait_for_callback
+from cloudinary_cli.auth.session import (
+    Session,
+    to_cloudinary_url,
+    from_cloudinary_url,
+    is_oauth_url,
+)
+from cloudinary_cli.auth.refresh import (
+    refresh_url_if_stale,
+    refresh_config,
+    refresh_configs,
+    relogin_command,
+    list_oauth_login_names,
+)
+from cloudinary_cli.defaults import logger, normalize_region, DEFAULT_REGION, CLOUDINARY_REGION
+from cloudinary_cli.utils.config_utils import (
+    load_config,
+    remove_config_keys,
+    save_named_config,
+    is_reserved_config_name,
+)
+from cloudinary_cli.utils.utils import log_exception, is_interactive
+
+__all__ = [
+    "login",
+    "logout",
+    "refresh_url_if_stale",
+    "refresh_config",
+    "refresh_configs",
+    "relogin_command",
+    "list_oauth_login_names",
+]
+
+
+def login(region=None, name=None, set_default=False):
+    """
+    Run the interactive browser login and persist the resulting session as a named config entry.
+
+    Returns (config_name, default_status), where default_status is:
+      "made"    - this login just became the default (explicit --set-default, or auto-defaulted as
+                  the sole login),
+      "already" - the re-logged-into config was already the stored default,
+      "no"      - it is not the default.
+    """
+    if name and is_reserved_config_name(name):
+        raise RuntimeError(f"'{name}' is a reserved configuration name.")
+    region = normalize_region(region or CLOUDINARY_REGION)
+    session = _run_browser_flow(region)
+    if not session.cloud_name:
+        raise RuntimeError("Login token did not include a cloud name; cannot save this login.")
+    config_name = name or _derive_config_name(session.cloud_name, region)
+
+    default_status = save_named_config(config_name, to_cloudinary_url(session), set_default=set_default)
+    return config_name, default_status
+
+
+def logout(name):
+    """
+    Log out of a saved OAuth login by name: revoke its refresh token at the authorization server,
+    then remove the saved configuration. The local entry is always removed even if revocation fails
+    (offline, server error), so logout never leaves a stale entry behind.
+
+    Returns "removed" (revoked and removed), "revoke_failed" (removed locally but the token could not
+    be revoked), "not_found", or "not_oauth".
+    """
+    saved = load_config()
+    if name not in saved:
+        return "not_found"
+    if not is_oauth_url(saved[name]):
+        return "not_oauth"
+
+    revoked = _revoke_login(name, saved[name])
+    remove_config_keys(name)
+    return "removed" if revoked else "revoke_failed"
+
+
+def _revoke_login(name, url):
+    """Best-effort revocation of a saved login's refresh token. Returns True on success (or when
+    there is nothing to revoke), False if the revoke request failed."""
+    session = from_cloudinary_url(url)
+    if not session.refresh_token:
+        return True
+    try:
+        flow.revoke(session.refresh_token, session.region)
+        return True
+    except requests.RequestException as e:
+        log_exception(e, debug_message=f"Could not revoke the OAuth token for '{name}'")
+        return False
+
+
+def _run_browser_flow(region):
+    verifier, challenge = flow.generate_pkce_pair()
+    state = secrets.token_urlsafe(16)
+    httpd, redirect_uri = start_callback_server()
+
+    authorize_url = flow.build_authorize_url(challenge, state, redirect_uri, region)
+    logger.info("Opening browser to log in to Cloudinary...")
+    opened = webbrowser.open(authorize_url)
+    if not opened and not is_interactive():
+        # No browser and no interactive terminal: nobody can complete the redirect, so fail fast
+        # instead of blocking until the callback times out. Headless runs use a pre-set config.
+        httpd.server_close()
+        raise RuntimeError(
+            "cld login needs an interactive browser session, but no browser could be opened and "
+            "this is not an interactive terminal. For headless/CI use, configure credentials with "
+            "an API-key URL instead: `cld -c cloudinary://<key>:<secret>@<cloud> <command>` or save "
+            "one with `cld config -n <name> <url>` and select it via `-C <name>`."
+        )
+    if not opened:
+        logger.info(f"Could not open a browser. Visit this URL to log in:\n{authorize_url}")
+    else:
+        logger.info(f"If it doesn't open automatically, visit:\n{authorize_url}")
+
+    auth_code, returned_state = wait_for_callback(httpd)
+    if returned_state != state:
+        raise RuntimeError("State mismatch - possible CSRF, aborting.")
+
+    token_response = flow.exchange_code(auth_code, verifier, redirect_uri, region)
+    return Session.from_token_response(token_response, region=region)
+
+
+def _derive_config_name(cloud_name, region):
+    """
+    Build the saved name: cloud_name + region geo suffix (when not default) + auth-type suffix
+    only when the base name collides with a DIFFERENT auth type (re-login overwrites in place).
+    """
+    base = cloud_name
+    if region != DEFAULT_REGION:
+        base = f"{base}-{region[len('api-'):]}"  # api-eu -> "<cloud>-eu"
+
+    config = load_config()
+    existing = config.get(base)
+    if existing is None or is_oauth_url(existing):
+        return base  # free, or same (oauth) type -> overwrite in place
+    return f"{base}-oauth"  # taken by an api-key config -> suffix the new oauth entry