cloudinary-cli 1.16.1__tar.gz → 1.18.0__tar.gz

{cloudinary_cli-1.16.1/cloudinary_cli.egg-info → cloudinary_cli-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloudinary-cli
-Version: 1.16.1
+Version: 1.18.0
 Summary: A command line interface for Cloudinary with full API support
 Home-page: https://github.com/cloudinary/cloudinary-cli
 Author: Cloudinary, Brian Luk
@@ -13,7 +13,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cloudinary>=1.45.0
+Requires-Dist: cloudinary>=1.47.0
 Requires-Dist: pygments
 Requires-Dist: jinja2
 Requires-Dist: click
@@ -35,11 +35,24 @@ The Cloudinary CLI (Command Line Interface) enables you to interact with Cloudin
 
 It is fully documented at [https://cloudinary.com/documentation/cloudinary_cli](https://cloudinary.com/documentation/cloudinary_cli).
 
+**Built for AI agents too.** [`cld agent cloud create`](#agent-cloud) provisions a working Cloudinary cloud in a single command — no signup, no verification email, no credentials to ask a human for — so an agent can start uploading and transforming right away, then hand the human a claim URL to keep it.
+
 ## 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.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.
 
+A Cloudinary account. There are two ways to get one:
+
+**Are you an AI agent?** Run [`cld agent cloud create`](#agent-cloud) — no signup, no verification email, no human in the loop. You get a working cloud name, API key and secret in one command, and can upload and transform immediately:
+
+```
+cld agent cloud create
+```
+
+The cloud is temporary: media delivery is limited to the IP that created it, and it expires in about 24 hours unless a human claims it. Hand them the claim URL from the output — or run [`cld agent cloud claim`](#agent-cloud) — and it becomes a permanent account, keeping the same credentials and everything already uploaded.
+
+**Are you a human?** Sign up at [https://cloudinary.com/users/register/free](https://cloudinary.com/users/register/free), then see [Configuration](#configuration) below. If you'd rather an agent set it up for you, [`cld agent signup`](#agent-signup) creates a Free-plan account in your name and emails you to verify it.
+
 ## Installation
 
 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.
@@ -168,7 +181,9 @@ 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 collections    # Lists Collections API methods.
 cld agent signup   # For AI agents: creates a Cloudinary account on behalf of a human.
+cld agent cloud    # For AI agents: creates a temporary cloud that works immediately.
 ```
 
 ## Docker Usage
@@ -248,6 +263,32 @@ cld admin transformation my_new_transformation
 
 _**Note:** you can omit 'admin' from the command when calling an Admin API method._
 
+## Collections API
+
+Enables you to run any methods that can be called through the collections API, to organize assets into collections and share them through public pages.
+
+You can find documentation for each of the Collections API methods at [https://cloudinary.com/documentation/collections_api](https://cloudinary.com/documentation/collections_api).
+
+The basic syntax using the Collections API is as follows:
+
+```
+cld [cli options] collections [command options] [method] [method parameters]
+```
+
+Example: create a collection, add an asset to it and publish it as a public page:
+
+```
+cld collections create_collection "Summer campaign" -o description "Campaign assets"
+cld collections add_collection_assets <collection_id> '["<asset_id>"]'
+cld collections create_collection_public_page <collection_id>
+```
+
+Create a dynamic collection from a search expression:
+
+```
+cld collections create_collection "Summer images" -o type dynamic -O configuration '{"expression": "tags=summer"}'
+```
+
 ## Search API
 
 Runs the admin API search method, allowing you to use a Lucene query string as the expression.
@@ -364,6 +405,70 @@ Options:
 * `--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.
 
+### `agent cloud`
+
+**For AI agents acting on behalf of a human.** Creates and claims *Claimable Clouds*: temporary clouds whose credentials work immediately, with no signup and no verification email. No existing configuration is required.
+
+Media delivery is restricted to an IP allow-list, and the cloud is **disabled after about 24 hours** — along with everything uploaded to it — unless a human claims it. Claiming makes it permanent, keeps the credentials and assets, and lifts the IP restriction.
+
+#### `agent cloud create`
+
+```
+cld agent cloud create [command options] [email]
+```
+
+Example:
+
+```
+cld agent cloud create you@example.com --claim
+```
+
+The cloud is saved as a named configuration along with its claim URL, which **the server returns exactly once and cannot be looked up again**. A cloud saved without it — or created outside the CLI — cannot be claimed via `agent cloud claim`.
+
+The optional `email` only pre-fills the claim page. It is never verified and no mail is sent to it at creation, but it must be a real unused address: the server rejects addresses already taken and disposable domains.
+
+Options:
+
+* `--ip <address>` — an additional IP permitted to deliver media, repeatable. Omit to let the server use the address the request comes from; the literal `requester_ip` means that same address.
+* `--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. The claim URL is then only in the output, so store it yourself.
+* `--claim` — open the claim page as soon as the cloud is created.
+* `--agent-framework <name>`, `--agent-llm-model <name>`, `--agent-goal <text>`, `--sdk-framework <name>` — attribution for the agent creating the cloud.
+* `--json` — output the full raw JSON response (the agent contract) instead of the human-readable summary.
+
+Delivery IPs are sent to the server as given; it validates them and returns the allow-list it actually stored. Read `delivery_ips` back from the response rather than assuming the list you sent was kept — behind a proxy or VPN your own address may be dropped, and the server refuses to create a cloud with no publicly routable address in the list.
+
+Because the allow-list covers media delivery only, the Upload and Admin APIs are unaffected. Uploads succeeding while a delivery URL returns `x-cld-error: ACL deny` is the expected symptom of the restriction, not a broken cloud or bad credentials. It is therefore not a confidentiality control.
+
+#### `agent cloud claim`
+
+```
+cld agent cloud claim [command options] [name]
+```
+
+Example:
+
+```
+cld agent cloud claim mycloud --print
+```
+
+Opens the claim page for a saved Claimable Cloud. Run without a name to pick from the saved clouds that have not expired.
+
+Claiming is a **human action completed in a browser**: they enter an email address there, then click the link sent to it. This command only opens or prints the page — it cannot claim anything itself, and nothing reports whether a claim succeeded.
+
+Options:
+
+* `--print` (or `--no-open`) — print the claim URL instead of opening a browser. Required for headless and agent use; also implied by `--json`. The CLI prints rather than opens whenever stdout is not a terminal.
+* `--json` — output `{cloud_name, claim_url, expires_at}` as JSON.
+
+Saved Claimable Clouds are flagged in `cld config -ls` and `cld config -s <name>` with an expiry countdown, so you can see what is still claimable:
+
+```
+NAME       CLOUD     TYPE     DEFAULT  ACTIVE  STATUS
+mycloud    abcd1234  api_key                   unclaimed, expires in 8h
+```
+
 ## 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.

{cloudinary_cli-1.16.1 → cloudinary_cli-1.18.0}/README.md

@@ -9,11 +9,24 @@ The Cloudinary CLI (Command Line Interface) enables you to interact with Cloudin
 
 It is fully documented at [https://cloudinary.com/documentation/cloudinary_cli](https://cloudinary.com/documentation/cloudinary_cli).
 
+**Built for AI agents too.** [`cld agent cloud create`](#agent-cloud) provisions a working Cloudinary cloud in a single command — no signup, no verification email, no credentials to ask a human for — so an agent can start uploading and transforming right away, then hand the human a claim URL to keep it.
+
 ## 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.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.
 
+A Cloudinary account. There are two ways to get one:
+
+**Are you an AI agent?** Run [`cld agent cloud create`](#agent-cloud) — no signup, no verification email, no human in the loop. You get a working cloud name, API key and secret in one command, and can upload and transform immediately:
+
+```
+cld agent cloud create
+```
+
+The cloud is temporary: media delivery is limited to the IP that created it, and it expires in about 24 hours unless a human claims it. Hand them the claim URL from the output — or run [`cld agent cloud claim`](#agent-cloud) — and it becomes a permanent account, keeping the same credentials and everything already uploaded.
+
+**Are you a human?** Sign up at [https://cloudinary.com/users/register/free](https://cloudinary.com/users/register/free), then see [Configuration](#configuration) below. If you'd rather an agent set it up for you, [`cld agent signup`](#agent-signup) creates a Free-plan account in your name and emails you to verify it.
+
 ## Installation
 
 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.
@@ -142,7 +155,9 @@ 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 collections    # Lists Collections API methods.
 cld agent signup   # For AI agents: creates a Cloudinary account on behalf of a human.
+cld agent cloud    # For AI agents: creates a temporary cloud that works immediately.
 ```
 
 ## Docker Usage
@@ -222,6 +237,32 @@ cld admin transformation my_new_transformation
 
 _**Note:** you can omit 'admin' from the command when calling an Admin API method._
 
+## Collections API
+
+Enables you to run any methods that can be called through the collections API, to organize assets into collections and share them through public pages.
+
+You can find documentation for each of the Collections API methods at [https://cloudinary.com/documentation/collections_api](https://cloudinary.com/documentation/collections_api).
+
+The basic syntax using the Collections API is as follows:
+
+```
+cld [cli options] collections [command options] [method] [method parameters]
+```
+
+Example: create a collection, add an asset to it and publish it as a public page:
+
+```
+cld collections create_collection "Summer campaign" -o description "Campaign assets"
+cld collections add_collection_assets <collection_id> '["<asset_id>"]'
+cld collections create_collection_public_page <collection_id>
+```
+
+Create a dynamic collection from a search expression:
+
+```
+cld collections create_collection "Summer images" -o type dynamic -O configuration '{"expression": "tags=summer"}'
+```
+
 ## Search API
 
 Runs the admin API search method, allowing you to use a Lucene query string as the expression.
@@ -338,6 +379,70 @@ Options:
 * `--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.
 
+### `agent cloud`
+
+**For AI agents acting on behalf of a human.** Creates and claims *Claimable Clouds*: temporary clouds whose credentials work immediately, with no signup and no verification email. No existing configuration is required.
+
+Media delivery is restricted to an IP allow-list, and the cloud is **disabled after about 24 hours** — along with everything uploaded to it — unless a human claims it. Claiming makes it permanent, keeps the credentials and assets, and lifts the IP restriction.
+
+#### `agent cloud create`
+
+```
+cld agent cloud create [command options] [email]
+```
+
+Example:
+
+```
+cld agent cloud create you@example.com --claim
+```
+
+The cloud is saved as a named configuration along with its claim URL, which **the server returns exactly once and cannot be looked up again**. A cloud saved without it — or created outside the CLI — cannot be claimed via `agent cloud claim`.
+
+The optional `email` only pre-fills the claim page. It is never verified and no mail is sent to it at creation, but it must be a real unused address: the server rejects addresses already taken and disposable domains.
+
+Options:
+
+* `--ip <address>` — an additional IP permitted to deliver media, repeatable. Omit to let the server use the address the request comes from; the literal `requester_ip` means that same address.
+* `--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. The claim URL is then only in the output, so store it yourself.
+* `--claim` — open the claim page as soon as the cloud is created.
+* `--agent-framework <name>`, `--agent-llm-model <name>`, `--agent-goal <text>`, `--sdk-framework <name>` — attribution for the agent creating the cloud.
+* `--json` — output the full raw JSON response (the agent contract) instead of the human-readable summary.
+
+Delivery IPs are sent to the server as given; it validates them and returns the allow-list it actually stored. Read `delivery_ips` back from the response rather than assuming the list you sent was kept — behind a proxy or VPN your own address may be dropped, and the server refuses to create a cloud with no publicly routable address in the list.
+
+Because the allow-list covers media delivery only, the Upload and Admin APIs are unaffected. Uploads succeeding while a delivery URL returns `x-cld-error: ACL deny` is the expected symptom of the restriction, not a broken cloud or bad credentials. It is therefore not a confidentiality control.
+
+#### `agent cloud claim`
+
+```
+cld agent cloud claim [command options] [name]
+```
+
+Example:
+
+```
+cld agent cloud claim mycloud --print
+```
+
+Opens the claim page for a saved Claimable Cloud. Run without a name to pick from the saved clouds that have not expired.
+
+Claiming is a **human action completed in a browser**: they enter an email address there, then click the link sent to it. This command only opens or prints the page — it cannot claim anything itself, and nothing reports whether a claim succeeded.
+
+Options:
+
+* `--print` (or `--no-open`) — print the claim URL instead of opening a browser. Required for headless and agent use; also implied by `--json`. The CLI prints rather than opens whenever stdout is not a terminal.
+* `--json` — output `{cloud_name, claim_url, expires_at}` as JSON.
+
+Saved Claimable Clouds are flagged in `cld config -ls` and `cld config -s <name>` with an expiry countdown, so you can see what is still claimable:
+
+```
+NAME       CLOUD     TYPE     DEFAULT  ACTIVE  STATUS
+mycloud    abcd1234  api_key                   unclaimed, expires in 8h
+```
+
 ## 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.

cloudinary_cli-1.18.0/cloudinary_cli/__init__.py

@@ -0,0 +1,9 @@
+from cloudinary_cli.version import __version__
+from cloudinary_cli.utils.env_config import import_sdk
+
+# Must run before any other `import cloudinary`, so that an invalid CLOUDINARY_URL does not stop the CLI.
+import_sdk()
+
+import cloudinary
+
+cloudinary.USER_PLATFORM = f"CloudinaryCLI/{__version__}"

{cloudinary_cli-1.16.1 → cloudinary_cli-1.18.0}/cloudinary_cli/cli_group.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import difflib
 import platform
 import shutil
 
@@ -13,7 +14,21 @@ from cloudinary_cli.version import __version__ as cli_version
 CONTEXT_SETTINGS = dict(max_content_width=shutil.get_terminal_size()[0], terminal_width=shutil.get_terminal_size()[0])
 
 
-@click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
+class SuggestingGroup(click.Group):
+    """Suggests similar command names when the command name is not known."""
+
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError as e:
+            names = [name for name in self.list_commands(ctx) if not self.get_command(ctx, name).hidden]
+            matches = difflib.get_close_matches(args[0], names) if args else []
+            if matches:
+                e.message += f"\nDid you mean: {', '.join(matches)}?"
+            raise
+
+
+@click.group(cls=SuggestingGroup, context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
 @click.help_option()
 @click.version_option(cli_version, prog_name="Cloudinary CLI",
                       message=f"%(prog)s, version %(version)s\n"

{cloudinary_cli-1.16.1 → cloudinary_cli-1.18.0}/cloudinary_cli/core/__init__.py

@@ -3,6 +3,7 @@ import click
 from cloudinary_cli.core.admin import admin
 from cloudinary_cli.core.agent import agent_group
 from cloudinary_cli.core.auth import login, logout
+from cloudinary_cli.core.collections import collections
 from cloudinary_cli.core.config import config_command
 from cloudinary_cli.core.search import search, search_folders
 from cloudinary_cli.core.uploader import uploader
@@ -22,6 +23,7 @@ commands = [
     admin,
     uploader,
     provisioning,
+    collections,
     url,
     utils
 ]

{cloudinary_cli-1.16.1 → cloudinary_cli-1.18.0}/cloudinary_cli/core/admin.py

@@ -16,11 +16,12 @@ Format: cld <cli options> admin <command options> <method> <method parameters>
 \t    cld admin resources max_results=10 -o tags sample
 """)
 @argument("params", nargs=-1)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o tags a,b")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O context '{\"alt\": \"cat\"}'")
 @option("-A", "--auto_paginate", is_flag=True, help="Will auto paginate Admin API calls.", default=False)
-@option("-ff", "--filter_fields", multiple=True, help="Filter fields to return when using auto pagination.")
+@option("-ff", "--filter_fields", multiple=True, help="Filter fields to return. Requires -A/--auto_paginate.")
 @option("-F", "--force", is_flag=True,
         help="Skip confirmations for auto pagination and destructive bulk API methods.")
 @option("-ls", "--ls", is_flag=True, help="List all available methods in the Admin API.")