setnilson · Oct 1, 2026 · Oct 1, 2026
diff --git a/.github/workflows/deploy-datadog-apps.yml b/.github/workflows/deploy-datadog-apps.yml
@@ -168,14 +168,22 @@ jobs:
           DD_APP_KEY: ${{ secrets.DATADOG_APP_KEY }}
         run: |
           if [ -z "$DD_API_KEY" ] || [ -z "$DD_APP_KEY" ]; then
-            echo "::error::DATADOG_API_KEY / DATADOG_APP_KEY are not set on this repository, so the upload can't authenticate. Without them it falls back to an interactive OAuth login, which hangs for 5 minutes on a CI runner before failing."
+            echo "::error::DATADOG_API_KEY / DATADOG_APP_KEY are not set on this repository, so the upload can't authenticate. Without them the datadog-apps CLI has no non-interactive credentials and exits with an error."
             echo "::error::Set them under Settings > Secrets and variables > Actions, or run: npm init @datadog/apps --set-secrets"
             exit 1
           fi
       - name: Upload ${{ matrix.app }}
+        working-directory: apps/${{ matrix.app }}
         env:
-          APP: ${{ matrix.app }}
           DD_API_KEY: ${{ secrets.DATADOG_API_KEY }}
           DD_SITE: datad0g.com
           DD_APP_KEY: ${{ secrets.DATADOG_APP_KEY }}
-        run: npm run upload -w "apps/$APP"
+        run: |
+          set -euo pipefail
+          "$GITHUB_WORKSPACE/node_modules/.bin/datadog-apps" upload \
+            --version-name "$GITHUB_SHA" \
+            | tee "$RUNNER_TEMP/upload.log"
+          if ! grep -q "Published version" "$RUNNER_TEMP/upload.log"; then
+            echo "::error::The upload exited 0 but never published a version. Treating this as a failed deploy: the app is NOT live. Check that the upload path still exists in the installed @datadog/apps-cli."
+            exit 1
+          fi
diff --git a/apps/clock/package.json b/apps/clock/package.json
@@ -6,7 +6,7 @@
     "dev": "vite",
     "dev:verify": "vite --mode dev-verify",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/k8s-pods/package.json b/apps/k8s-pods/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/my-first-app/package.json b/apps/my-first-app/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --ext ts,tsx --fix",
     "preview": "vite preview",
@@ -21,4 +21,4 @@
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.3.0"
   }
-}
+}
diff --git a/apps/openai-prompt/docs/agents/build-upload-auth.md b/apps/openai-prompt/docs/agents/build-upload-auth.md
@@ -7,9 +7,12 @@ This scaffold uses npm. Prefer the scripts in `package.json` over ad hoc command
 - `npm run dev` — start the local Vite dev server.
 - `npm run typecheck` — TypeScript check without emitting files. Use this for credential-free validation.
 - `npm run lint` / `npm run lint:fix` — run ESLint.
-- `npm run build` — production build (does not deploy by default).
-- `npm run deploy` — build, upload, and publish the app live.
-- `npm run publish` — publish the most recently uploaded version without rebuilding.
+- `npm run build` — local production build. Writes `dist/datadog-app-assets.zip` and uploads nothing.
+- `npm run upload` — build, upload, and publish the app live, via the `datadog-apps` CLI
+  (`@datadog/apps-cli`, a root devDependency). This is the only script that makes an app go live.
+
+There are no `deploy` or `publish` scripts in this workspace. Uploading and publishing are a
+single `upload` step: the CLI uploads the bundle, then releases that version to live.
 
 ## App identity (do not change)
 
@@ -133,12 +136,17 @@ The application key needs both scopes enabled — not just one:
 
 Go to `https://app.datadoghq.com/organization-settings/application-keys`, confirm both scopes, or create a new key with both.
 
-**Build succeeds but nothing deploys**
-
-- Use `npm run deploy`, not `npm run build`, when the intent is to deploy.
-- Check whether `DD_APPS_PUBLISH` is set to `false` in the environment — the app uploads as a draft but does not go live. Unset the variable or run `npm run publish` separately.
-- Confirm `dryRun` in `vite.config.ts` is not `true`.
-- Confirm `DD_APPS_UPLOAD_ASSETS` is set — `npm run deploy` does this automatically.
+**Build succeeds but nothing goes live**
+
+- Use `npm run upload`, not `npm run build`. `build` only writes the zip.
+- Check that the `upload` script runs `npx datadog-apps upload` and not a bare `vite build`.
+  `@datadog/vite-plugin` 3.3.0 dropped the in-build upload path, so a `vite build`
+  spelled as "upload" exits 0 having published nothing. This exact regression took
+  `scott-mountains` live-less while CI reported success (PR #14).
+- A successful upload prints `Published version <id> live.` followed by the app's URL.
+  If that line is absent, nothing was published, whatever the exit code says.
+- `DD_APPS_UPLOAD_ASSETS` is not read by any version of the plugin or the CLI. If you
+  see it in a script, that script is stale.
 
 **Build fails with missing credentials**
 

diff --git a/apps/openai-prompt/package.json b/apps/openai-prompt/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-mon-aug-31-1-17-54-pm/package.json b/apps/sarah-s-app-mon-aug-31-1-17-54-pm/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-mon-aug-31-1-42-47-pm/docs/agents/build-upload-auth.md b/apps/sarah-s-app-mon-aug-31-1-42-47-pm/docs/agents/build-upload-auth.md
@@ -7,9 +7,12 @@ This scaffold uses npm. Prefer the scripts in `package.json` over ad hoc command
 - `npm run dev` — start the local Vite dev server.
 - `npm run typecheck` — TypeScript check without emitting files. Use this for credential-free validation.
 - `npm run lint` / `npm run lint:fix` — run ESLint.
-- `npm run build` — production build (does not deploy by default).
-- `npm run deploy` — build, upload, and publish the app live.
-- `npm run publish` — publish the most recently uploaded version without rebuilding.
+- `npm run build` — local production build. Writes `dist/datadog-app-assets.zip` and uploads nothing.
+- `npm run upload` — build, upload, and publish the app live, via the `datadog-apps` CLI
+  (`@datadog/apps-cli`, a root devDependency). This is the only script that makes an app go live.
+
+There are no `deploy` or `publish` scripts in this workspace. Uploading and publishing are a
+single `upload` step: the CLI uploads the bundle, then releases that version to live.
 
 ## App identity (do not change)
 
@@ -133,12 +136,17 @@ The application key needs both scopes enabled — not just one:
 
 Go to `https://app.datadoghq.com/organization-settings/application-keys`, confirm both scopes, or create a new key with both.
 
-**Build succeeds but nothing deploys**
-
-- Use `npm run deploy`, not `npm run build`, when the intent is to deploy.
-- Check whether `DD_APPS_PUBLISH` is set to `false` in the environment — the app uploads as a draft but does not go live. Unset the variable or run `npm run publish` separately.
-- Confirm `dryRun` in `vite.config.ts` is not `true`.
-- Confirm `DD_APPS_UPLOAD_ASSETS` is set — `npm run deploy` does this automatically.
+**Build succeeds but nothing goes live**
+
+- Use `npm run upload`, not `npm run build`. `build` only writes the zip.
+- Check that the `upload` script runs `npx datadog-apps upload` and not a bare `vite build`.
+  `@datadog/vite-plugin` 3.3.0 dropped the in-build upload path, so a `vite build`
+  spelled as "upload" exits 0 having published nothing. This exact regression took
+  `scott-mountains` live-less while CI reported success (PR #14).
+- A successful upload prints `Published version <id> live.` followed by the app's URL.
+  If that line is absent, nothing was published, whatever the exit code says.
+- `DD_APPS_UPLOAD_ASSETS` is not read by any version of the plugin or the CLI. If you
+  see it in a script, that script is stale.
 
 **Build fails with missing credentials**
 

diff --git a/apps/sarah-s-app-mon-aug-31-1-42-47-pm/package.json b/apps/sarah-s-app-mon-aug-31-1-42-47-pm/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-thu-sep-3-3-40-03-pm/docs/agents/build-upload-auth.md b/apps/sarah-s-app-thu-sep-3-3-40-03-pm/docs/agents/build-upload-auth.md
@@ -7,9 +7,12 @@ This scaffold uses npm. Prefer the scripts in `package.json` over ad hoc command
 - `npm run dev` — start the local Vite dev server.
 - `npm run typecheck` — TypeScript check without emitting files. Use this for credential-free validation.
 - `npm run lint` / `npm run lint:fix` — run ESLint.
-- `npm run build` — production build (does not deploy by default).
-- `npm run deploy` — build, upload, and publish the app live.
-- `npm run publish` — publish the most recently uploaded version without rebuilding.
+- `npm run build` — local production build. Writes `dist/datadog-app-assets.zip` and uploads nothing.
+- `npm run upload` — build, upload, and publish the app live, via the `datadog-apps` CLI
+  (`@datadog/apps-cli`, a root devDependency). This is the only script that makes an app go live.
+
+There are no `deploy` or `publish` scripts in this workspace. Uploading and publishing are a
+single `upload` step: the CLI uploads the bundle, then releases that version to live.
 
 ## App identity (do not change)
 
@@ -133,12 +136,17 @@ The application key needs both scopes enabled — not just one:
 
 Go to `https://app.datadoghq.com/organization-settings/application-keys`, confirm both scopes, or create a new key with both.
 
-**Build succeeds but nothing deploys**
-
-- Use `npm run deploy`, not `npm run build`, when the intent is to deploy.
-- Check whether `DD_APPS_PUBLISH` is set to `false` in the environment — the app uploads as a draft but does not go live. Unset the variable or run `npm run publish` separately.
-- Confirm `dryRun` in `vite.config.ts` is not `true`.
-- Confirm `DD_APPS_UPLOAD_ASSETS` is set — `npm run deploy` does this automatically.
+**Build succeeds but nothing goes live**
+
+- Use `npm run upload`, not `npm run build`. `build` only writes the zip.
+- Check that the `upload` script runs `npx datadog-apps upload` and not a bare `vite build`.
+  `@datadog/vite-plugin` 3.3.0 dropped the in-build upload path, so a `vite build`
+  spelled as "upload" exits 0 having published nothing. This exact regression took
+  `scott-mountains` live-less while CI reported success (PR #14).
+- A successful upload prints `Published version <id> live.` followed by the app's URL.
+  If that line is absent, nothing was published, whatever the exit code says.
+- `DD_APPS_UPLOAD_ASSETS` is not read by any version of the plugin or the CLI. If you
+  see it in a script, that script is stale.
 
 **Build fails with missing credentials**
 

diff --git a/apps/sarah-s-app-thu-sep-3-3-40-03-pm/package.json b/apps/sarah-s-app-thu-sep-3-3-40-03-pm/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-tue-aug-25-10-32-30-am/package.json b/apps/sarah-s-app-tue-aug-25-10-32-30-am/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --ext ts,tsx --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-wed-aug-26-2-14-31-pm/package.json b/apps/sarah-s-app-wed-aug-26-2-14-31-pm/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --ext ts,tsx --fix",
     "preview": "vite preview",

diff --git a/apps/sarah-s-app-wed-sep-23-4-09-23-pm/package.json b/apps/sarah-s-app-wed-sep-23-4-09-23-pm/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+    "upload": "npx datadog-apps upload",
     "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",

diff --git a/apps/scott-mountains/package.json b/apps/scott-mountains/package.json
@@ -5,7 +5,7 @@
     "scripts": {
         "dev": "vite",
         "build": "vite build",
-        "upload": "DD_APPS_UPLOAD_ASSETS=1 vite build",
+        "upload": "npx datadog-apps upload",
         "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
         "lint:fix": "eslint . --fix",
         "preview": "vite preview",

diff --git a/docs/agents/build-upload-auth.md b/docs/agents/build-upload-auth.md
@@ -7,9 +7,12 @@ This scaffold uses npm. Prefer the scripts in `package.json` over ad hoc command
 - `npm run dev` — start the local Vite dev server.
 - `npm run typecheck` — TypeScript check without emitting files. Use this for credential-free validation.
 - `npm run lint` / `npm run lint:fix` — run ESLint.
-- `npm run build` — production build (does not deploy by default).
-- `npm run deploy` — build, upload, and publish the app live.
-- `npm run publish` — publish the most recently uploaded version without rebuilding.
+- `npm run build` — local production build. Writes `dist/datadog-app-assets.zip` and uploads nothing.
+- `npm run upload` — build, upload, and publish the app live, via the `datadog-apps` CLI
+  (`@datadog/apps-cli`, a root devDependency). This is the only script that makes an app go live.
+
+There are no `deploy` or `publish` scripts in this workspace. Uploading and publishing are a
+single `upload` step: the CLI uploads the bundle, then releases that version to live.
 
 ## App identity (do not change)
 
@@ -133,12 +136,17 @@ The application key needs both scopes enabled — not just one:
 
 Go to `https://app.datadoghq.com/organization-settings/application-keys`, confirm both scopes, or create a new key with both.
 
-**Build succeeds but nothing deploys**
-
-- Use `npm run deploy`, not `npm run build`, when the intent is to deploy.
-- Check whether `DD_APPS_PUBLISH` is set to `false` in the environment — the app uploads as a draft but does not go live. Unset the variable or run `npm run publish` separately.
-- Confirm `dryRun` in `vite.config.ts` is not `true`.
-- Confirm `DD_APPS_UPLOAD_ASSETS` is set — `npm run deploy` does this automatically.
+**Build succeeds but nothing goes live**
+
+- Use `npm run upload`, not `npm run build`. `build` only writes the zip.
+- Check that the `upload` script runs `npx datadog-apps upload` and not a bare `vite build`.
+  `@datadog/vite-plugin` 3.3.0 dropped the in-build upload path, so a `vite build`
+  spelled as "upload" exits 0 having published nothing. This exact regression took
+  `scott-mountains` live-less while CI reported success (PR #14).
+- A successful upload prints `Published version <id> live.` followed by the app's URL.
+  If that line is absent, nothing was published, whatever the exit code says.
+- `DD_APPS_UPLOAD_ASSETS` is not read by any version of the plugin or the CLI. If you
+  see it in a script, that script is stale.
 
 **Build fails with missing credentials**
 

diff --git a/docs/agents/cicd.md b/docs/agents/cicd.md
@@ -1,11 +1,11 @@
 # CI/CD
 
-This monorepo ships a deploy workflow at `.github/workflows/deploy-datadog-apps.yml`. You do not need to add `DataDog/apps-github-action` — the workflow uploads each app through its own `upload` script, which respects the npm workspace layout.
+This monorepo ships a deploy workflow at `.github/workflows/deploy-datadog-apps.yml`. You do not need to add `DataDog/apps-github-action` — the workflow uploads each app with the root-installed `datadog-apps` CLI, run from that app's directory so it picks up the app's own `datadog-app.config.json`.
 
 ## What the workflow does
 
 - **On pull requests** touching `apps/**`, `packages/**`, or the root package manifests: runs `npm ci`, checks every app manifest against the root React overrides, then runs `npm run typecheck`, `npm run lint`, and `npm run build` as merge gates. No Datadog credentials are used.
-- **On pushes to the repository's default branch**: runs `npm ci --ignore-scripts` and the same React-alignment check, then detects which `apps/<name>` folders changed and uploads only those, one matrix leg per app, via `npm run upload -w apps/<name>`. Uploads do not run when the lockfile or alignment gate fails.
+- **On pushes to the repository's default branch**: runs `npm ci --ignore-scripts` and the same React-alignment check, then detects which `apps/<name>` folders changed and uploads only those, one matrix leg per app, via `node_modules/.bin/datadog-apps upload --version-name "$GITHUB_SHA"`. The step fails if the CLI exits 0 without printing `Published version`, so a no-op upload cannot pass as a green deploy. Uploads do not run when the lockfile or alignment gate fails.
 
 Re-uploading an app **updates the existing Datadog App** rather than creating a new one, because each app's `vite.config.ts` carries a stable `apps.identifier`. So editing an app becomes: open a PR, merge it, and the app updates in Datadog.
 
@@ -15,7 +15,7 @@ The default branch is read from `github.event.repository.default_branch`, so the
 
 ## Required secrets
 
-Store `DATADOG_API_KEY` and `DATADOG_APP_KEY` as [encrypted secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) in the repository or organization settings. Prefer an application key owned by a [service account](https://docs.datadoghq.com/account_management/org_settings/service_accounts/) rather than a personal user key — a personal key stops working when that user is deactivated, silently breaking the pipeline. The key needs both **Actions API Access** and **Apps** scopes. The workflow passes the secrets to the build as `DD_API_KEY` / `DD_APP_KEY`, which the Datadog vite plugin reads to authenticate the upload.
+Store `DATADOG_API_KEY` and `DATADOG_APP_KEY` as [encrypted secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) in the repository or organization settings. Prefer an application key owned by a [service account](https://docs.datadoghq.com/account_management/org_settings/service_accounts/) rather than a personal user key — a personal key stops working when that user is deactivated, silently breaking the pipeline. The key needs both **Actions API Access** and **Apps** scopes. The workflow passes the secrets to the upload step as `DD_API_KEY` / `DD_APP_KEY`, which the `datadog-apps` CLI reads to authenticate. When only one of the two is set, the CLI ignores both and falls back to OAuth, which cannot complete in CI.
 
 ## Datadog site