@cloudinary/apps-cli

CLI for scaffolding and managing Cloudinary DAM custom-action apps.

Requirements: Node.js >= 20

Install

npm install -g @cloudinary/apps-cli

This installs the cld-apps binary.

Quick start

cld-apps create my-dam-app
cd my-dam-app
pnpm install
pnpm dev

Dev server: http://localhost:7179

Commands

| Command | Description | | ------------------------------------------------- | ---------------------------------------------- | | cld-apps create <app-name> | Scaffold a new DAM app | | cld-apps login | Authenticate via browser and store credentials | | cld-apps logout [cloud-name] | Remove stored credentials | | cld-apps whoami | Show active cloud / credentials | | cld-apps use <cloud-name> | Switch active cloud | | cld-apps manifest create [path] | Create cloudinary.app.json (+ schema) | | cld-apps manifest validate [path] | Validate a manifest | | cld-apps manifest push [options] | Push manifest to Cloudinary | | cld-apps manifest push:watch [options] | Watch and push on change | | cld-apps deploy <staging\|production> [options] | Build, zip, and deploy | | cld-apps get-config [options] | Fetch live DamConfig | | cld-apps ci <link\|status\|unlink> <tier> | Let GitHub Actions deploy the app (CI link) | | cld-apps --version | Print package version |

Run cld-apps with no args for full usage.

Auth

cld-apps login

The login code expires about 60 seconds after it is issued, so sign in to the Cloudinary console first. In a terminal, the command waits for Enter before it requests a login code, which gives you time to do that. It then opens a browser login page with the code already in the URL. If the browser does not open, copy the printed URL (it contains the code).

Pass --no-wait to skip the pause. That is for agents and other tools that run commands in a terminal, where nobody is there to press Enter.

Credentials are stored locally. Override with CLOUDINARY_GATEWAY_TOKEN when needed.

Deploying from GitHub Actions

A GitHub Actions job can run deploy and manifest push with no stored secret. The app's creator links the app to the repository once per tier:

cld-apps ci link production --branch master        # repo defaults to the origin remote
cld-apps ci link staging --event pull_request
cld-apps ci status production

ci link opens a fresh browser login and hands it to the gateway, which keeps it for the link: CI deploys as the account you log in with. Your stored login is not touched. Pass at least one of --branch, --event or --environment, so the link does not trust every workflow in the repository. If ci status shows BROKEN (the login was revoked, or the user lost access), run ci link again.

In the workflow, give the job id-token: write. The CLI then requests the job's OIDC token itself, after the build:

permissions:
  contents: read
  id-token: write
steps:
  - run: pnpm exec cld-apps deploy production

Order of credentials for deploy and manifest push: CLOUDINARY_GATEWAY_TOKEN, then the GitHub Actions OIDC token, then the stored login.

Optional env:

• CLOUDINARY_GATEWAY_URL — gateway base URL
• CLOUDINARY_APP_ID — Custom Action app id (also via .env.<tier>)

Publishing this package (maintainers)

From cli/:

./bin/publish

Publishes @cloudinary/apps-cli to the public npm registry (--access public). Requires npm auth with publish rights to the @cloudinary scope.

Related packages

• @cloudinary/apps-api — typed API gateway client (CLI dependency)
• @cloudinary/apps-sdk — shared utilities for DAM apps (scaffold dependency)