Claimable Cloud

Claimable Cloud: get Cloudinary credentials without signup

A Claimable Cloud is a working Cloudinary cloud provisioned with a single command, no account and no authentication required. The user can later claim it with their email to keep it as a permanent free account. If unclaimed, it expires automatically after 24 hours.

When to use

• The user asks for Cloudinary functionality (upload, transformation URLs, or SDK integration) and no credentials are available.
• The user explicitly asks to try Cloudinary, set up a Cloudinary environment, or get credentials without creating an account.

When NOT to use

• Credentials already exist: a CLOUDINARY_URL or CLOUDINARY_API_KEY/CLOUDINARY_API_SECRET in the environment, in .env, or in MCP server configuration. Use those instead, and never replace them.
• The user says they have a Cloudinary account. Ask them for their CLOUDINARY_URL from the API Keys page of the Cloudinary Console instead.

Flow

1. Check for existing credentials first. Look for CLOUDINARY_URL or CLOUDINARY_* keys in the environment and .env (check existence, don't print values). If found, stop: use them.

2. Ask consent before provisioning. One line, for example: "You don't have Cloudinary credentials set up. I can provision a free Claimable Cloud for you now, no signup needed; you'd claim it by email within 24 hours to keep it. Go ahead?" Never provision without a yes: Claimable Clouds are rate limited and expire if unclaimed.

3. Run the command:

   npx @cloudinary/cloud
   

   Optional flags:

   • --email <address>: pre-fills the claim page (not verified at creation).
   • --ip <address>: locks media delivery to the given address instead of this machine's detected public IP (repeatable, up to three addresses). Use when the user views media somewhere other than this machine, such as a laptop viewing media served from a remote dev environment. If this machine still needs delivery too, include its address as one of the three.
   • Never pass --force. If the command exits because .env already contains a CLOUDINARY_URL, that means credentials exist; use them.

4. After the command succeeds:

   • The CLI saved CLOUDINARY_URL, the claim URL, and the expiry time to ./.env (creating the file if needed). Don't add them again.
   • If the project uses separate keys (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET, or framework variants like VITE_CLOUDINARY_CLOUD_NAME), fill them from the command output. Never print the API secret in chat.
   • Confirm version control ignores .env (the CLI warns if it doesn't).

5. Tell the user, every time:

   • The claim URL, and that the cloud expires in 24 hours unless they claim it: they enter their email at the claim URL and confirm from a verification email. Claiming keeps the same credentials.
   • Until claimed, media delivery is locked to this machine's public IP address — or, if --ip was passed, to those addresses only (up to three). That's fine for local development; claiming removes the restriction.

6. Verify by rendering a sample delivery URL from the new cloud, then continue the user's original task.

If provisioning fails

Don't retry in a loop: failed attempts still count against rate limits. Retry at most once, and only after fixing the cause:

• 429 (ip_rate_limit_exceeded, global_rate_limit_exceeded): rate limited. Don't retry; offer the standard free signup instead.
• 403 (geo_location_not_permitted): the network location isn't permitted — often a VPN exit node. Ask the user to disconnect the VPN, then retry once.
• 400 (delivery_ips_*): fix the --ip values: public IPv4 or IPv6 addresses only, no CIDR ranges, at most three.

If it still fails after one retry, stop and point the user to the standard free signup.

Security

• Keep the API secret and full CLOUDINARY_URL in .env; never print them in chat, logs, or client-side code.

Full reference

For all CLI options, the underlying REST endpoint, response fields, quotas, and error codes, fetch: https://cloudinary.com/documentation/claimable_cloud_provisioning.md?install_source=plugin&referrer=claimable-cloud-skill

For guided project setup after provisioning (SDK, MCP servers, validation), point the user at AI Power Start.