fix: clarify eas-cli upgrade instructions

packages/eas-cli/README.md

@@ -14,28 +14,34 @@ EAS command line tool
 # Installation
 
 ```sh
+npx eas-cli@latest
+# optional: create a shorthand alias
+alias eas="npx eas-cli@latest"
+# or instlal globally
 npm install -g eas-cli
-# or
-yarn global add eas-cli
 ```
 
 ## Enforcing eas-cli version for your project
 
-If you want to enforce the `eas-cli` version for your project, use the `"cli.version"` field in **eas.json**. Installing `eas-cli` to your project dependencies is strongly discouraged because it may cause dependency conflicts that are difficult to debug.
+Use the `"cli.version"` field in **eas.json** to enforce a minimum version. When invoked via `npx eas-cli@latest`, it will prompt to install the latest version if missing or outdated. This installs to your machine's `npx` cache, not your project's `node_modules` or `package.json`.
+
+## Installation local to your project is strongly discouraged
+
+Adding `eas-cli` to your project's dependencies is strongly discouraged as it may cause difficult-to-debug dependency conflicts. Use `npx` or install globally with `npm install -g eas-cli`.
 
 An example of **eas.json** that enforces `eas-cli` in version `1.0.0` or newer:
 
 ```json
 {
-  "cli": {
-    "version": ">=1.0.0"
-  },
-  "build": {
-    // build profiles
-  },
-  "submit": {
-    // submit profiles
-  }
+    "cli": {
+        "version": ">=1.0.0"
+    },
+    "build": {
+        // build profiles
+    },
+    "submit": {
+        // submit profiles
+    }
 }
 ```
 
@@ -55,109 +61,110 @@ eas --help COMMAND
 # Commands
 
 <!-- commands -->
-* [`eas account:login`](#eas-accountlogin)
-* [`eas account:logout`](#eas-accountlogout)
-* [`eas account:usage [ACCOUNT_NAME]`](#eas-accountusage-account_name)
-* [`eas account:view`](#eas-accountview)
-* [`eas analytics [STATUS]`](#eas-analytics-status)
-* [`eas autocomplete [SHELL]`](#eas-autocomplete-shell)
-* [`eas branch:create [NAME]`](#eas-branchcreate-name)
-* [`eas branch:delete [NAME]`](#eas-branchdelete-name)
-* [`eas branch:list`](#eas-branchlist)
-* [`eas branch:rename`](#eas-branchrename)
-* [`eas branch:view [NAME]`](#eas-branchview-name)
-* [`eas build`](#eas-build)
-* [`eas build:cancel [BUILD_ID]`](#eas-buildcancel-build_id)
-* [`eas build:configure`](#eas-buildconfigure)
-* [`eas build:delete [BUILD_ID]`](#eas-builddelete-build_id)
-* [`eas build:dev`](#eas-builddev)
-* [`eas build:download`](#eas-builddownload)
-* [`eas build:inspect`](#eas-buildinspect)
-* [`eas build:list`](#eas-buildlist)
-* [`eas build:resign`](#eas-buildresign)
-* [`eas build:run`](#eas-buildrun)
-* [`eas build:submit`](#eas-buildsubmit)
-* [`eas build:version:get`](#eas-buildversionget)
-* [`eas build:version:set`](#eas-buildversionset)
-* [`eas build:version:sync`](#eas-buildversionsync)
-* [`eas build:view [BUILD_ID]`](#eas-buildview-build_id)
-* [`eas channel:create [NAME]`](#eas-channelcreate-name)
-* [`eas channel:delete [NAME]`](#eas-channeldelete-name)
-* [`eas channel:edit [NAME]`](#eas-channeledit-name)
-* [`eas channel:list`](#eas-channellist)
-* [`eas channel:pause [NAME]`](#eas-channelpause-name)
-* [`eas channel:resume [NAME]`](#eas-channelresume-name)
-* [`eas channel:rollout [CHANNEL]`](#eas-channelrollout-channel)
-* [`eas channel:view [NAME]`](#eas-channelview-name)
-* [`eas config`](#eas-config)
-* [`eas credentials`](#eas-credentials)
-* [`eas credentials:configure-build`](#eas-credentialsconfigure-build)
-* [`eas deploy [options]`](#eas-deploy-options)
-* [`eas deploy:alias`](#eas-deployalias)
-* [`eas deploy:alias:delete [ALIAS_NAME]`](#eas-deployaliasdelete-alias_name)
-* [`eas deploy:delete [DEPLOYMENT_ID]`](#eas-deploydelete-deployment_id)
-* [`eas deploy:promote`](#eas-deploypromote)
-* [`eas device:create`](#eas-devicecreate)
-* [`eas device:delete`](#eas-devicedelete)
-* [`eas device:list`](#eas-devicelist)
-* [`eas device:rename`](#eas-devicerename)
-* [`eas device:view [UDID]`](#eas-deviceview-udid)
-* [`eas diagnostics`](#eas-diagnostics)
-* [`eas env:create [ENVIRONMENT]`](#eas-envcreate-environment)
-* [`eas env:delete [ENVIRONMENT]`](#eas-envdelete-environment)
-* [`eas env:exec ENVIRONMENT BASH_COMMAND`](#eas-envexec-environment-bash_command)
-* [`eas env:get [ENVIRONMENT]`](#eas-envget-environment)
-* [`eas env:list [ENVIRONMENT]`](#eas-envlist-environment)
-* [`eas env:pull [ENVIRONMENT]`](#eas-envpull-environment)
-* [`eas env:push [ENVIRONMENT]`](#eas-envpush-environment)
-* [`eas env:update [ENVIRONMENT]`](#eas-envupdate-environment)
-* [`eas fingerprint:compare [HASH1] [HASH2]`](#eas-fingerprintcompare-hash1-hash2)
-* [`eas fingerprint:generate`](#eas-fingerprintgenerate)
-* [`eas help [COMMAND]`](#eas-help-command)
-* [`eas init`](#eas-init)
-* [`eas init:onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-initonboarding-target_project_directory)
-* [`eas login`](#eas-login)
-* [`eas logout`](#eas-logout)
-* [`eas metadata:lint`](#eas-metadatalint)
-* [`eas metadata:pull`](#eas-metadatapull)
-* [`eas metadata:push`](#eas-metadatapush)
-* [`eas new [PATH]`](#eas-new-path)
-* [`eas onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-onboarding-target_project_directory)
-* [`eas open`](#eas-open)
-* [`eas project:info`](#eas-projectinfo)
-* [`eas project:init`](#eas-projectinit)
-* [`eas project:new [PATH]`](#eas-projectnew-path)
-* [`eas project:onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-projectonboarding-target_project_directory)
-* [`eas submit`](#eas-submit)
-* [`eas update`](#eas-update)
-* [`eas update:configure`](#eas-updateconfigure)
-* [`eas update:delete GROUPID`](#eas-updatedelete-groupid)
-* [`eas update:edit [GROUPID]`](#eas-updateedit-groupid)
-* [`eas update:list`](#eas-updatelist)
-* [`eas update:republish`](#eas-updaterepublish)
-* [`eas update:revert-update-rollout`](#eas-updaterevert-update-rollout)
-* [`eas update:roll-back-to-embedded`](#eas-updateroll-back-to-embedded)
-* [`eas update:rollback`](#eas-updaterollback)
-* [`eas update:view GROUPID`](#eas-updateview-groupid)
-* [`eas upload`](#eas-upload)
-* [`eas webhook:create`](#eas-webhookcreate)
-* [`eas webhook:delete [ID]`](#eas-webhookdelete-id)
-* [`eas webhook:list`](#eas-webhooklist)
-* [`eas webhook:update`](#eas-webhookupdate)
-* [`eas webhook:view ID`](#eas-webhookview-id)
-* [`eas whoami`](#eas-whoami)
-* [`eas worker:alias`](#eas-workeralias)
-* [`eas worker:alias:delete [ALIAS_NAME]`](#eas-workeraliasdelete-alias_name)
-* [`eas worker:delete [DEPLOYMENT_ID]`](#eas-workerdelete-deployment_id)
-* [`eas deploy [options]`](#eas-deploy-options-1)
-* [`eas workflow:cancel`](#eas-workflowcancel)
-* [`eas workflow:create [NAME]`](#eas-workflowcreate-name)
-* [`eas workflow:logs [ID]`](#eas-workflowlogs-id)
-* [`eas workflow:run [FILE]`](#eas-workflowrun-file)
-* [`eas workflow:runs`](#eas-workflowruns)
-* [`eas workflow:status [WORKFLOW_RUN_ID]`](#eas-workflowstatus-workflow_run_id)
-* [`eas workflow:validate PATH`](#eas-workflowvalidate-path)
-* [`eas workflow:view [ID]`](#eas-workflowview-id)
+
+- [`eas account:login`](#eas-accountlogin)
+- [`eas account:logout`](#eas-accountlogout)
+- [`eas account:usage [ACCOUNT_NAME]`](#eas-accountusage-account_name)
+- [`eas account:view`](#eas-accountview)
+- [`eas analytics [STATUS]`](#eas-analytics-status)
+- [`eas autocomplete [SHELL]`](#eas-autocomplete-shell)
+- [`eas branch:create [NAME]`](#eas-branchcreate-name)
+- [`eas branch:delete [NAME]`](#eas-branchdelete-name)
+- [`eas branch:list`](#eas-branchlist)
+- [`eas branch:rename`](#eas-branchrename)
+- [`eas branch:view [NAME]`](#eas-branchview-name)
+- [`eas build`](#eas-build)
+- [`eas build:cancel [BUILD_ID]`](#eas-buildcancel-build_id)
+- [`eas build:configure`](#eas-buildconfigure)
+- [`eas build:delete [BUILD_ID]`](#eas-builddelete-build_id)
+- [`eas build:dev`](#eas-builddev)
+- [`eas build:download`](#eas-builddownload)
+- [`eas build:inspect`](#eas-buildinspect)
+- [`eas build:list`](#eas-buildlist)
+- [`eas build:resign`](#eas-buildresign)
+- [`eas build:run`](#eas-buildrun)
+- [`eas build:submit`](#eas-buildsubmit)
+- [`eas build:version:get`](#eas-buildversionget)
+- [`eas build:version:set`](#eas-buildversionset)
+- [`eas build:version:sync`](#eas-buildversionsync)
+- [`eas build:view [BUILD_ID]`](#eas-buildview-build_id)
+- [`eas channel:create [NAME]`](#eas-channelcreate-name)
+- [`eas channel:delete [NAME]`](#eas-channeldelete-name)
+- [`eas channel:edit [NAME]`](#eas-channeledit-name)
+- [`eas channel:list`](#eas-channellist)
+- [`eas channel:pause [NAME]`](#eas-channelpause-name)
+- [`eas channel:resume [NAME]`](#eas-channelresume-name)
+- [`eas channel:rollout [CHANNEL]`](#eas-channelrollout-channel)
+- [`eas channel:view [NAME]`](#eas-channelview-name)
+- [`eas config`](#eas-config)
+- [`eas credentials`](#eas-credentials)
+- [`eas credentials:configure-build`](#eas-credentialsconfigure-build)
+- [`eas deploy [options]`](#eas-deploy-options)
+- [`eas deploy:alias`](#eas-deployalias)
+- [`eas deploy:alias:delete [ALIAS_NAME]`](#eas-deployaliasdelete-alias_name)
+- [`eas deploy:delete [DEPLOYMENT_ID]`](#eas-deploydelete-deployment_id)
+- [`eas deploy:promote`](#eas-deploypromote)
+- [`eas device:create`](#eas-devicecreate)
+- [`eas device:delete`](#eas-devicedelete)
+- [`eas device:list`](#eas-devicelist)
+- [`eas device:rename`](#eas-devicerename)
+- [`eas device:view [UDID]`](#eas-deviceview-udid)
+- [`eas diagnostics`](#eas-diagnostics)
+- [`eas env:create [ENVIRONMENT]`](#eas-envcreate-environment)
+- [`eas env:delete [ENVIRONMENT]`](#eas-envdelete-environment)
+- [`eas env:exec ENVIRONMENT BASH_COMMAND`](#eas-envexec-environment-bash_command)
+- [`eas env:get [ENVIRONMENT]`](#eas-envget-environment)
+- [`eas env:list [ENVIRONMENT]`](#eas-envlist-environment)
+- [`eas env:pull [ENVIRONMENT]`](#eas-envpull-environment)
+- [`eas env:push [ENVIRONMENT]`](#eas-envpush-environment)
+- [`eas env:update [ENVIRONMENT]`](#eas-envupdate-environment)
+- [`eas fingerprint:compare [HASH1] [HASH2]`](#eas-fingerprintcompare-hash1-hash2)
+- [`eas fingerprint:generate`](#eas-fingerprintgenerate)
+- [`eas help [COMMAND]`](#eas-help-command)
+- [`eas init`](#eas-init)
+- [`eas init:onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-initonboarding-target_project_directory)
+- [`eas login`](#eas-login)
+- [`eas logout`](#eas-logout)
+- [`eas metadata:lint`](#eas-metadatalint)
+- [`eas metadata:pull`](#eas-metadatapull)
+- [`eas metadata:push`](#eas-metadatapush)
+- [`eas new [PATH]`](#eas-new-path)
+- [`eas onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-onboarding-target_project_directory)
+- [`eas open`](#eas-open)
+- [`eas project:info`](#eas-projectinfo)
+- [`eas project:init`](#eas-projectinit)
+- [`eas project:new [PATH]`](#eas-projectnew-path)
+- [`eas project:onboarding [TARGET_PROJECT_DIRECTORY]`](#eas-projectonboarding-target_project_directory)
+- [`eas submit`](#eas-submit)
+- [`eas update`](#eas-update)
+- [`eas update:configure`](#eas-updateconfigure)
+- [`eas update:delete GROUPID`](#eas-updatedelete-groupid)
+- [`eas update:edit [GROUPID]`](#eas-updateedit-groupid)
+- [`eas update:list`](#eas-updatelist)
+- [`eas update:republish`](#eas-updaterepublish)
+- [`eas update:revert-update-rollout`](#eas-updaterevert-update-rollout)
+- [`eas update:roll-back-to-embedded`](#eas-updateroll-back-to-embedded)
+- [`eas update:rollback`](#eas-updaterollback)
+- [`eas update:view GROUPID`](#eas-updateview-groupid)
+- [`eas upload`](#eas-upload)
+- [`eas webhook:create`](#eas-webhookcreate)
+- [`eas webhook:delete [ID]`](#eas-webhookdelete-id)
+- [`eas webhook:list`](#eas-webhooklist)
+- [`eas webhook:update`](#eas-webhookupdate)
+- [`eas webhook:view ID`](#eas-webhookview-id)
+- [`eas whoami`](#eas-whoami)
+- [`eas worker:alias`](#eas-workeralias)
+- [`eas worker:alias:delete [ALIAS_NAME]`](#eas-workeraliasdelete-alias_name)
+- [`eas worker:delete [DEPLOYMENT_ID]`](#eas-workerdelete-deployment_id)
+- [`eas deploy [options]`](#eas-deploy-options-1)
+- [`eas workflow:cancel`](#eas-workflowcancel)
+- [`eas workflow:create [NAME]`](#eas-workflowcreate-name)
+- [`eas workflow:logs [ID]`](#eas-workflowlogs-id)
+- [`eas workflow:run [FILE]`](#eas-workflowrun-file)
+- [`eas workflow:runs`](#eas-workflowruns)
+- [`eas workflow:status [WORKFLOW_RUN_ID]`](#eas-workflowstatus-workflow_run_id)
+- [`eas workflow:validate PATH`](#eas-workflowvalidate-path)
+- [`eas workflow:view [ID]`](#eas-workflowview-id)
 
 ## `eas account:login`
 
@@ -2500,4 +2507,5 @@ DESCRIPTION
 ```
 
 _See code: [packages/eas-cli/src/commands/workflow/view.ts](https://github.com/expo/eas-cli/blob/v18.0.3/packages/eas-cli/src/commands/workflow/view.ts)_
+
 <!-- commandsstop -->

packages/eas-cli/package.json

@@ -236,11 +236,11 @@
       }
     },
     "warn-if-update-available": {
-      "message": "<%= chalk('★') %> <%= chalk.bold(config.name + '@' + latest) %> <%= chalk.bold('is now available.') %>\n<%= chalk.dim('To upgrade, run:') %>\n<%= chalk.dim(chalk.bold('npm install -g eas-cli')) %>\n<%= chalk.dim('Proceeding with outdated version.') %>\n",
+      "message": "<%= chalk('★') %> <%= chalk.bold(config.name + '@' + latest) %> <%= chalk.bold('is now available.') %>\n<%= chalk.dim('To upgrade:') %>\n<%= chalk.dim('  • npx: update') %> <%= chalk.dim(chalk.bold('cli.version')) %> <%= chalk.dim('in eas.json') %>\n<%= chalk.dim('  • global: npm install -g eas-cli') %>\n<%= chalk.dim('Proceeding with outdated version.') %>\n",
       "timeoutInDays": 0.5
     }
   },
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}

packages/eas-cli/src/commandUtils/context/contextUtils/findProjectDirAndVerifyProjectSetupAsync.ts

@@ -1,15 +1,16 @@
-import { EasJsonAccessor, EasJsonUtils } from '@expo/eas-json';
 import * as PackageManagerUtils from '@expo/package-manager';
+
+import { EasJsonAccessor, EasJsonUtils } from '@expo/eas-json';
+
 import chalk from 'chalk';
+import { easCliVersion } from '../../../utils/easCli';
 import fs from 'fs-extra';
 import getenv from 'getenv';
+import { learnMore } from '../../../log';
 import path from 'path';
 import pkgDir from 'pkg-dir';
-import semver from 'semver';
-
-import { learnMore } from '../../../log';
-import { easCliVersion } from '../../../utils/easCli';
 import { resolveVcsClient } from '../../../vcs';
+import semver from 'semver';
 
 async function applyCliConfigAsync(projectDir: string): Promise<void> {
   const easJsonAccessor = EasJsonAccessor.fromProjectPath(projectDir);
@@ -23,11 +24,12 @@ async function applyCliConfigAsync(projectDir: string): Promise<void> {
     !semver.satisfies(easCliVersion, config.version)
   ) {
     throw new Error(
-      `You are on eas-cli@${easCliVersion} which does not satisfy the CLI version constraint defined in eas.json (${
-        config.version
-      }).\n\nThis error probably means that you need update your eas-cli to a newer version.\nRun ${chalk.bold(
+      `You are on eas-cli@${easCliVersion} which does not satisfy the CLI version constraint defined in eas.json (${config.version
+      }).\n\nUpdate eas-cli to a compatible version:\n  ${chalk.bold(
+        'npx eas-cli@latest'
+      )}\n  or install globally: ${chalk.bold(
         'npm install -g eas-cli'
-      )} to update the eas-cli to the latest version.`
+      )}`
     );
   }
 }
@@ -101,7 +103,7 @@ export async function findProjectRootAsync({
     let vcsRoot;
     try {
       vcsRoot = path.normalize(await resolveVcsClient().getRootPathAsync());
-    } catch {}
+    } catch { }
     if (vcsRoot && vcsRoot.startsWith(projectRootDir) && vcsRoot !== projectRootDir) {
       throw new Error(
         `package.json is outside of the current git repository (project root: ${projectRootDir}, git root: ${vcsRoot}.`