@metaplay/metaplay-auth 1.4.2 → 1.6.0

package/index.ts

@@ -1,41 +1,196 @@
 #!/usr/bin/env node
 import { Command } from 'commander'
 import Docker from 'dockerode'
-import { loginAndSaveTokens, machineLoginAndSaveTokens, extendCurrentSession, loadTokens, removeTokens } from './src/auth.js'
-import { StackAPI, type GameserverId } from './src/stackapi.js'
-import { checkGameServerDeployment } from './src/deployment.js'
+import { portalBaseUrl, setPortalBaseUrl } from './src/config.js'
+import {
+  loginAndSaveTokens,
+  machineLoginAndSaveTokens,
+  extendCurrentSession,
+  loadTokens,
+  removeTokens,
+  TokenSet,
+} from './src/auth.js'
+import { checkGameServerDeployment, debugGameServer } from './src/deployment.js'
+import {
+  pathJoin,
+  isValidFQDN,
+  executeCommand,
+  removeTrailingSlash,
+  fetchHelmChartVersions,
+  resolveBestMatchingVersion,
+} from './src/utils.js'
 import { logger, setLogLevel } from './src/logging.js'
-import { isValidFQDN, executeCommand } from './src/utils.js'
+import { TargetEnvironment } from './src/targetenvironment.js'
 import { exit } from 'process'
 import { tmpdir } from 'os'
-import { join } from 'path'
 import { randomBytes } from 'crypto'
 import { writeFile, unlink } from 'fs/promises'
 import { existsSync } from 'fs'
 import { KubeConfig } from '@kubernetes/client-node'
 import * as semver from 'semver'
+import { PACKAGE_VERSION } from './src/version.js'
+import { registerBuildCommand } from './src/buildCommand.js'
 
 /**
- * Helper for parsing the GameserverId type from the command line arguments. Accepts either the gameserver address
+ * Base URL of StackAPI infra to use -- defaults to p1.metaplay.io. Override with the global --stack-api flag.
+ * Note: The dynamic `kubeconfig`s generated by `metaplay-auth` override this with '--stack-api <url>' flag.
+ */
+let defaultStackApiBaseUrl = 'https://infra.p1.metaplay.io/stackapi'
+
+/**
+ * Resolve a TargetEnvironment from a fully-qualified domain name (eg, 'idler-develop.p1.metaplay.io').
+ * @param tokens Tokens to use for authenticating with the portal
+ * @param environmentDomain The environment domain name (eg, 'idler-develop.p1.metaplay.io')
+ * @returns The TargetEnvironment instance needed to operate with the environment.
+ */
+function resolveTargetEnvironmentFromFQDN(tokens: TokenSet, environmentDomain: string): TargetEnvironment {
+  // Extract the humanId from the domain, eg: 'idler-develop.p1.metaplay.io' -> 'idler-develop'
+  const humanId = environmentDomain.split('.')[0]
+  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl) // \todo We could probably infer the stack API URL from the domain?
+}
+
+/**
+ * Information about an environment received from the portal.
+ */
+// \todo Should share this type with the portal endpoint code that returns
+interface PortalEnvironmentInfo {
+  /** UUID of the environment */
+  id: string
+
+  /** UUID of the project */
+  project_id: string
+
+  /** User-provided name for the environment (can change) */
+  name: string
+
+  /** TODO: What is this URL? */
+  url: string
+
+  /** Slug for the environment (simplified version of name) */
+  slug: string
+
+  /** Creation time of the environment (eg, '2024-02-02T08:20:18.457748+00:00') */
+  created_at: string
+
+  /** Type of the environment (eg, 'development' or 'production') */
+  type: string
+
+  /** Immutable human-readable identifier for the environment (eg, 'delicious-pumpkin' .. can also be legacy name like 'idler-develop') */
+  // \todo Make field mandatory when portal returns valid values
+  human_id?: string
+
+  // \todo Add stackapi url that the portal should return?
+}
+
+/**
+ * Fetch information about a specific managed environment from the Metaplay portal using slugs.
+ * @param tokens Tokens to use to for authenticating with the portal.
+ * @param organization Organization slug.
+ * @param project Project slug.
+ * @param environment Environment slug.
+ * @returns The portal's information about the environment.
+ */
+// eslint-disable-next-line @typescript-eslint/max-params
+async function fetchManagedEnvironmentInfo(
+  tokens: TokenSet,
+  organization: string,
+  project: string,
+  environment: string
+): Promise<PortalEnvironmentInfo> {
+  const url = `${portalBaseUrl}/api/v1/environments/with-slugs?organization_slug=${organization}&project_slug=${project}&environment_slug=${environment}`
+  logger.debug(`Getting environment information from portal: ${url}...`)
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${tokens.access_token}`,
+      'Content-Type': 'application/json',
+    },
+  })
+
+  // Throw on server errors (eg, forbidden)
+  if (!response.ok) {
+    const errorData = await response.json()
+    throw new Error(`Failed to fetch environment details with error ${response.status}: ${JSON.stringify(errorData)}`)
+  }
+
+  // \todo Validate response?
+  return (await response.json()) as PortalEnvironmentInfo
+}
+
+/**
+ * Resolve the target environment based on (org, proj, env) tuple. We fetch the information
+ * from the portal and then construct the `TargetEnvironment` class with the required information
+ * for downstream operations.
+ * @param tokens Tokens to use for authenticating with the portal
+ * @param organization Organization slug.
+ * @param project Project slug.
+ * @param environment Environment slug.
+ * @returns The TargetEnvironment instance needed to operate with the environment.
+ */
+// eslint-disable-next-line @typescript-eslint/max-params
+async function resolveTargetEnvironmentFromSlugs(
+  tokens: TokenSet,
+  organization: string,
+  project: string,
+  environment: string
+): Promise<TargetEnvironment> {
+  // Fetch the deployment information from the portal
+  const portalEnvInfo = await fetchManagedEnvironmentInfo(tokens, organization, project, environment)
+  // \todo Use legacy '<project>-<environment>' -- should be filled in by portal!
+  const humanId = portalEnvInfo.human_id ?? `${project}-${environment}`
+
+  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl)
+}
+
+async function resolveTargetEnvironmentHumanId(tokens: TokenSet, humanId: string): Promise<TargetEnvironment> {
+  // \todo Validate that the target environment exists?
+
+  return new TargetEnvironment(tokens.access_token, humanId, defaultStackApiBaseUrl)
+}
+
+/**
+ * Helper for parsing the TargetEnvironment type from the command line arguments. Accepts either the gameserver address
  * (idler-test.p1.metaplay.io), a shorthand address (metaplay-idler-test) or the (organization, project, environment)
  * tuple from options.
  */
-function resolveGameserverId (address: string | undefined, options: any): GameserverId {
+async function resolveTargetEnvironment(
+  address: string | undefined,
+  options: { organization?: string; project?: string; environment?: string }
+): Promise<TargetEnvironment> {
+  const tokens = await loadTokens()
+
   // If address is specified, use it, otherwise assume options has organization, project, and environment
   if (address) {
+    // Address is one of:
+    // - FQDN of the target environment, eg, 'idler-develop.p1.metaplay.io'
+    // - Tuple of '<organization>-<project>-<environment>' slugs (eg, 'metaplay-idler-develop')
+    // - Stable humanId, eg, 'delicious-elephant'
     if (isValidFQDN(address)) {
-      return { gameserver: address }
+      return resolveTargetEnvironmentFromFQDN(tokens, address)
     } else {
       const parts = address.split('-')
-      if (parts.length !== 3) {
-        throw new Error('Invalid gameserver address syntax: specify either <organization>-<project>-<environment> or a fully-qualified domain name (eg, idler-develop.p1.metaplay.io)')
+      if (parts.length === 2) {
+        // Two parts is humanId, eg, 'delicious-elephant'
+        return await resolveTargetEnvironmentHumanId(tokens, address)
+      } else if (parts.length === 3) {
+        // Three parts is tuple of slush '<organization>-<project>-<environment>'
+        return await resolveTargetEnvironmentFromSlugs(tokens, parts[0], parts[1], parts[2])
+      } else {
+        throw new Error(
+          `Invalid environment address syntax '${address}'. Specify either "<organization>-<project>-<environment>", a humanId (eg, "delicious-elephant"), or a fully-qualified domain name (eg, idler-develop.p1.metaplay.io)`
+        )
       }
-      return { organization: parts[0], project: parts[1], environment: parts[2] }
     }
   } else if (options.organization && options.project && options.environment) {
-    return { organization: options.organization, project: options.project, environment: options.environment }
+    // Parse tuple from command-line options (output to stderr to avoid messing up '$(eval metaplay-auth ... --format env)' invocations
+    console.warn(
+      `Warning: Specifying the target environment with -o (--organization), -p (--project), and -e (--environment) is deprecated! Use the '${options.organization}-${options.project}-${options.environment}' syntax instead.`
+    )
+    return await resolveTargetEnvironmentFromSlugs(tokens, options.organization, options.project, options.environment)
   } else {
-    throw new Error('Could not determine target environment from arguments: You need to specify either a gameserver address or an organization, project, and environment. Run this command with --help flag for more information.')
+    throw new Error(
+      'Could not determine target environment from arguments: You need to specify either an environment FQDN or an organization, project, and environment. Run this command with --help flag for more information.'
+    )
   }
 }
 
@@ -44,8 +199,13 @@ const program = new Command()
 program
   .name('metaplay-auth')
   .description('Authenticate with Metaplay and get AWS and Kubernetes credentials for game servers.')
-  .version('1.4.2')
+  .version(PACKAGE_VERSION)
   .option('-d, --debug', 'enable debug output')
+  .option('--portal-base-url <portal-base-url>', 'override the default portal base URL (e.g. http://localhost:3000)')
+  .option(
+    '--stack-api <stack-api-base-url>',
+    'override the default stack API base URL (e.g. https://infra.p1.metaplay.io/stackapi/)'
+  )
   .hook('preAction', (thisCommand) => {
     // Handle debug flag for all commands.
     const opts = thisCommand.opts()
@@ -54,24 +214,42 @@ program
     } else {
       setLogLevel(10)
     }
+
+    // Store the portal base URL for accessing globally
+    if (opts.portalBaseUrl) {
+      setPortalBaseUrl(opts.portalBaseUrl as string)
+    }
+
+    // Store the stack API base URL for accessing globally
+    if (opts.stackApi) {
+      defaultStackApiBaseUrl = opts.stackApi as string
+    }
   })
 
-program.command('login')
+program
+  .command('login')
   .description('login to your Metaplay account')
   .action(async () => {
     await loginAndSaveTokens()
   })
 
-program.command('machine-login')
-  .description('login to the Metaplay cloud using a machine account (using credentials in environment variable METAPLAY_CREDENTIALS)')
-  .option('--dev-credentials', 'machine user credentials to use, only for dev purposes, use METAPLAY_CREDENTIALS env variable for better safety!')
+program
+  .command('machine-login')
+  .description(
+    'login to the Metaplay cloud using a machine account (using credentials in environment variable METAPLAY_CREDENTIALS)'
+  )
+  .option(
+    '--dev-credentials',
+    'machine user credentials to use, only for dev purposes, use METAPLAY_CREDENTIALS env variable for better safety!'
+  )
   .action(async (options) => {
     // Get credentials from command line or from METAPLAY_CREDENTIALS environment variable
-    let credentials
+    let credentials: string
     if (options.devCredentials) {
       credentials = options.devCredentials
     } else {
-      credentials = process.env.METAPLAY_CREDENTIALS
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      credentials = process.env.METAPLAY_CREDENTIALS!
       if (!credentials || credentials === '') {
         throw new Error('Unable to find the credentials, the environment variable METAPLAY_CREDENTIALS is not defined!')
       }
@@ -81,7 +259,9 @@ program.command('machine-login')
     // \note We can't be certain that the secret does not contain pluses so split at the first occurrence
     const splitOffset = credentials.indexOf('+')
     if (splitOffset === -1) {
-      throw new Error('Invalid format for credentials, you should copy-paste the value from the developer portal verbatim')
+      throw new Error(
+        'Invalid format for credentials, you should copy-paste the value from the developer portal verbatim'
+      )
     }
     const clientId = credentials.substring(0, splitOffset)
     const clientSecret = credentials.substring(splitOffset + 1)
@@ -90,7 +270,8 @@ program.command('machine-login')
     await machineLoginAndSaveTokens(clientId, clientSecret)
   })
 
-program.command('logout')
+program
+  .command('logout')
   .description('log out of your Metaplay account')
   .action(async () => {
     console.log('Logging out by removing locally stored tokens...')
@@ -107,16 +288,17 @@ program.command('logout')
     }
   })
 
-program.command('show-tokens')
+program
+  .command('show-tokens')
   .description('show loaded tokens')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (options) => {
+  .action(async () => {
     try {
       // TODO: Could detect if not logged in and fail more gracefully?
       const tokens = await loadTokens()
-      console.log(tokens)
+      console.log(JSON.stringify(tokens, undefined, 2))
     } catch (error) {
       if (error instanceof Error) {
         console.error(`Error showing tokens: ${error.message}`)
@@ -125,55 +307,62 @@ program.command('show-tokens')
     }
   })
 
-program.command('get-kubeconfig')
+program
+  .command('get-kubeconfig')
   .description('get kubeconfig for target environment')
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
-  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
-  .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
-  .option('-p, --project <project>', 'project name (e.g. idler)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .option('-t, --type <credentials-type>', 'type of credentials handling in kubeconfig (static or dynamic)')
-  .option('--output <kubeconfig-path>', 'path of the output file where to write kubeconfig (written to stdout if not specified)')
+  .option(
+    '--output <kubeconfig-path>',
+    'path of the output file where to write kubeconfig (written to stdout if not specified)'
+  )
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
-    try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
-
-      // Default to credentialsType==dynamic for human users, and credentialsType==static for machine users
-      const isHumanUser = !!tokens.refresh_token
-      const credentialsType = options.credentialsType ?? (isHumanUser ? 'dynamic' : 'static')
-
-      // Generate kubeconfig
-      let kubeconfigPayload
-      if (credentialsType === 'dynamic') {
-        logger.debug('Fetching kubeconfig with execcredential')
-        kubeconfigPayload = await stackApi.getKubeConfigExecCredential(gameserverId)
-      } else if (credentialsType === 'static') {
-        logger.debug('Fetching kubeconfig with embedded secret')
-        kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
-      } else {
-        throw new Error('Invalid credentials type; must be either "static" or "dynamic"')
-      }
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string; type?: string; output?: string }
+    ) => {
+      try {
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
+
+        // Default to credentialsType==dynamic for human users, and credentialsType==static for machine users
+        const tokens = await loadTokens()
+        const isHumanUser = !!tokens.refresh_token
+        const credentialsType = options.type ?? (isHumanUser ? 'dynamic' : 'static')
+
+        // Generate kubeconfig
+        let kubeconfigPayload
+        if (credentialsType === 'dynamic') {
+          logger.debug('Fetching kubeconfig with execcredential')
+          kubeconfigPayload = await targetEnv.getKubeConfigWithExecCredential()
+        } else if (credentialsType === 'static') {
+          logger.debug('Fetching kubeconfig with embedded secret')
+          kubeconfigPayload = await targetEnv.getKubeConfigWithEmbeddedCredentials()
+        } else {
+          throw new Error('Invalid credentials type; must be either "static" or "dynamic"')
+        }
 
-      // Write kubeconfig to output (file or stdout)
-      if (options.output) {
-        logger.debug(`Writing kubeconfig to file ${options.output}`)
-        await writeFile(options.output, kubeconfigPayload, { mode: 0o600 })
-        console.log(`Wrote kubeconfig to ${options.output}`)
-      } else {
-        console.log(kubeconfigPayload)
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error('Error getting KubeConfig:', error)
+        // Write kubeconfig to output (file or stdout)
+        if (options.output) {
+          logger.debug(`Writing kubeconfig to file ${options.output}`)
+          await writeFile(options.output, kubeconfigPayload, { mode: 0o600 })
+          console.log(`Wrote kubeconfig to ${options.output}`)
+        } else {
+          console.log(kubeconfigPayload)
+        }
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error('Error getting KubeConfig:', error)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
 /**
  * Get the Kubernetes credentials in the execcredential format which can be used within the `kubeconfig` file:
@@ -183,473 +372,583 @@ program.command('get-kubeconfig')
  * kubeconfig that uses this command.
  */
 // todo: maybe this should be a hidden command as it's not very useful for end users and clutters help?
-program.command('get-kubernetes-execcredential')
+program
+  .command('get-kubernetes-execcredential')
   .description('[internal] get kubernetes credentials in execcredential format (used from the generated kubeconfigs)')
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
-  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
-  .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
-  .option('-p, --project <project>', 'project name (e.g. idler)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
-    try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
-
-      const credentials = await stackApi.getKubeExecCredential(gameserverId)
-      console.log(credentials)
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error getting Kubernetes ExecCredential: ${error.message}`)
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string }
+    ) => {
+      try {
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
+        const credentials = await targetEnv.getKubeExecCredential()
+        console.log(credentials)
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`Error getting Kubernetes ExecCredential: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('get-aws-credentials')
+program
+  .command('get-aws-credentials')
   .description('get AWS credentials for target environment')
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
-  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
-  .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
-  .option('-p, --project <project>', 'project name (e.g. idler)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .option('-f, --format <format>', 'output format (json or env)', 'json')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
-    try {
-      if (options.format !== 'json' && options.format !== 'env') {
-        throw new Error('Invalid format; must be one of json or env')
-      }
-
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
-
-      const credentials = await stackApi.getAwsCredentials(gameserverId)
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string; format?: string }
+    ) => {
+      try {
+        if (options.format !== 'json' && options.format !== 'env') {
+          throw new Error('Invalid format; must be one of json or env')
+        }
 
-      if (options.format === 'env') {
-        console.log(`export AWS_ACCESS_KEY_ID=${credentials.AccessKeyId}`)
-        console.log(`export AWS_SECRET_ACCESS_KEY=${credentials.SecretAccessKey}`)
-        console.log(`export AWS_SESSION_TOKEN=${credentials.SessionToken}`)
-      } else {
-        console.log(JSON.stringify({
-          ...credentials,
-          Version: 1 // this is needed to comply with `aws` format for external credential providers
-        }))
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error getting AWS credentials: ${error.message}`)
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
+
+        // Get the AWS credentials
+        const credentials = await targetEnv.getAwsCredentials()
+
+        if (options.format === 'env') {
+          console.log(`export AWS_ACCESS_KEY_ID=${credentials.AccessKeyId}`)
+          console.log(`export AWS_SECRET_ACCESS_KEY=${credentials.SecretAccessKey}`)
+          console.log(`export AWS_SESSION_TOKEN=${credentials.SessionToken}`)
+        } else {
+          console.log(
+            JSON.stringify({
+              ...credentials,
+              Version: 1, // this is needed to comply with `aws` format for external credential providers
+            })
+          )
+        }
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`Error getting AWS credentials: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('get-docker-login')
-  .description('get docker login credentials for pushing the server image to target environment')
+program
+  .command('get-docker-login')
+  .description('[deprecated] get docker login credentials for pushing the server image to target environment')
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
-  .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
-  .option('-p, --project <project>', 'project name (e.g. idler)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .option('-f, --format <format>', 'output format (json or env)', 'json')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
-    try {
-      if (options.format !== 'json' && options.format !== 'env') {
-        throw new Error('Invalid format; must be one of json or env')
-      }
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string; format?: string }
+    ) => {
+      try {
+        if (options.format !== 'json' && options.format !== 'env') {
+          throw new Error('Invalid format; must be one of json or env')
+        }
 
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
-
-      // Get environment info (region is needed for ECR)
-      logger.debug('Get environment info')
-      const environment = await stackApi.getEnvironmentDetails(gameserverId)
-      const dockerRepo = environment.deployment.ecr_repo
-
-      // Resolve docker credentials for remote registry
-      logger.debug('Get docker credentials')
-      const dockerCredentials = await stackApi.getDockerCredentials(gameserverId)
-      const { username, password } = dockerCredentials
-
-      // Output the docker repo & credentials
-      if (options.format === 'env') {
-        console.log(`export DOCKER_REPO=${dockerRepo}`)
-        console.log(`export DOCKER_USERNAME=${username}`)
-        console.log(`export DOCKER_PASSWORD=${password}`)
-      } else {
-        console.log(JSON.stringify({
-          dockerRepo,
-          username,
-          password
-        }))
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error getting docker login credentials: ${error.message}`)
+        console.warn('The get-docker-login command is deprecated! Use the push-docker-image command instead.')
+
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
+
+        // Get environment info (region is needed for ECR)
+        logger.debug('Get environment info')
+        const environment = await targetEnv.getEnvironmentDetails()
+        const dockerRepo = environment.deployment.ecr_repo
+
+        // Resolve docker credentials for remote registry
+        logger.debug('Get docker credentials')
+        const dockerCredentials = await targetEnv.getDockerCredentials()
+        const { username, password } = dockerCredentials
+
+        // Output the docker repo & credentials
+        if (options.format === 'env') {
+          console.log(`export DOCKER_REPO=${dockerRepo}`)
+          console.log(`export DOCKER_USERNAME=${username}`)
+          console.log(`export DOCKER_PASSWORD=${password}`)
+        } else {
+          console.log(
+            JSON.stringify({
+              dockerRepo,
+              username,
+              password,
+            })
+          )
+        }
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`Error getting docker login credentials: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('get-environment')
+program
+  .command('get-environment')
   .description('get details of an environment')
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
-  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
-  .option('-o, --organization <organization>', 'organization name (e.g. metaplay)')
-  .option('-p, --project <project>', 'project name (e.g. idler)')
-  .option('-e, --environment <environment>', 'environment name (e.g. develop)')
+  .option('-o, --organization <organization>', '[deprecated] organization name (e.g. metaplay)')
+  .option('-p, --project <project>', '[deprecated] project name (e.g. idler)')
+  .option('-e, --environment <environment>', '[deprecated] environment name (e.g. develop)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, options) => {
-    try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string }
+    ) => {
+      try {
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      const environment = await stackApi.getEnvironmentDetails(gameserverId)
-      console.log(JSON.stringify(environment))
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error getting environment details: ${error.message}`)
+        const environment = await targetEnv.getEnvironmentDetails()
+        console.log(JSON.stringify(environment, undefined, 2))
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`Error getting environment details: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('push-docker-image')
+program
+  .command('push-docker-image')
   .description('push docker image into the target environment image registry')
   .argument('gameserver', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
   .argument('image-name', 'full name of the docker image to push (eg, the gameserver:<sha>)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, imageName, options) => {
-    try {
-      console.log(`Pushing docker image ${imageName} to target environment ${gameserver}...`)
+  .action(
+    async (
+      gameserver: string | undefined,
+      imageName: string | undefined,
+      options: { organization?: string; project?: string; environment?: string; imageTag?: string }
+    ) => {
+      try {
+        console.log(`Pushing docker image ${imageName} to target environment ${gameserver}...`)
 
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      // Get environment info (region is needed for ECR)
-      logger.debug('Get environment info')
-      const envInfo = await stackApi.getEnvironmentDetails(gameserverId)
+        // Get environment info (region is needed for ECR)
+        logger.debug('Get environment info')
+        const envInfo = await targetEnv.getEnvironmentDetails()
 
-      // Resolve docker credentials for remote registry
-      logger.debug('Get docker credentials')
-      const dockerCredentials = await stackApi.getDockerCredentials(gameserverId)
+        // Resolve docker credentials for remote registry
+        logger.debug('Get docker credentials')
+        const dockerCredentials = await targetEnv.getDockerCredentials()
 
-      // Resolve tag from src image
-      if (!imageName) {
-        throw new Error('Must specify a valid docker image name as the image-name argument')
-      }
-      const srcImageParts = imageName.split(':')
-      if (srcImageParts.length !== 2 || srcImageParts[0].length === 0 || srcImageParts[1].length === 0) {
-        throw new Error(`Invalid docker image name '${imageName}', expecting the name in format 'name:tag'`)
-      }
-      const imageTag = srcImageParts[1]
-
-      // Resolve source image
-      const srcImageName = imageName
-      const dstRepoName = envInfo.deployment.ecr_repo
-      const dstImageName = `${dstRepoName}:${imageTag}`
-      const dockerApi = new Docker()
-      const srcDockerImage = dockerApi.getImage(srcImageName)
-
-      // If names don't match, tag the src image as dst
-      if (srcImageName !== dstImageName) {
-        logger.debug(`Tagging image ${srcImageName} as ${dstImageName}`)
-        await srcDockerImage.tag({ repo: dstRepoName, tag: imageTag })
-      }
+        // Resolve tag from src image
+        if (!imageName) {
+          throw new Error('Must specify a valid docker image name as the image-name argument')
+        }
+        const srcImageParts = imageName.split(':')
+        if (srcImageParts.length !== 2 || srcImageParts[0].length === 0 || srcImageParts[1].length === 0) {
+          throw new Error(`Invalid docker image name '${imageName}', expecting the name in format 'name:tag'`)
+        }
+        const imageTag = srcImageParts[1]
+
+        // Resolve source image
+        const srcImageName = imageName
+        const dstRepoName = envInfo.deployment.ecr_repo
+        const dstImageName = `${dstRepoName}:${imageTag}`
+        const dockerApi = new Docker()
+        const srcDockerImage = dockerApi.getImage(srcImageName)
+
+        // If names don't match, tag the src image as dst
+        if (srcImageName !== dstImageName) {
+          logger.debug(`Tagging image ${srcImageName} as ${dstImageName}`)
+          await srcDockerImage.tag({ repo: dstRepoName, tag: imageTag })
+        }
 
-      // Push the image
-      logger.debug(`Push image ${dstImageName}`)
-      const dstDockerImage = dockerApi.getImage(dstImageName)
-      const authConfig = { username: dockerCredentials.username, password: dockerCredentials.password, serveraddress: dockerCredentials.registryUrl }
-      const pushStream = await dstDockerImage.push({ authconfig: authConfig, tag: options.imageTag })
-
-      // Follow push progress & wait until completed
-      logger.debug('Following image push stream...')
-      await new Promise((resolve, reject) => {
-        dockerApi.modem.followProgress(
-          pushStream,
-          (error: Error | null, result: any[]) => {
-            if (error) {
-              logger.debug('Failed to push image:', error)
-              reject(error)
-            } else {
-              // result contains an array of all the progress objects
-              logger.debug('Succesfully finished pushing image')
-              resolve(result)
+        // Push the image
+        logger.debug(`Push image ${dstImageName}`)
+        const dstDockerImage = dockerApi.getImage(dstImageName)
+        const authConfig = {
+          username: dockerCredentials.username,
+          password: dockerCredentials.password,
+          serveraddress: dockerCredentials.registryUrl,
+        }
+        const pushStream = await dstDockerImage.push({ authconfig: authConfig, tag: options.imageTag })
+
+        // Follow push progress & wait until completed
+        logger.debug('Following image push stream...')
+        await new Promise((resolve, reject) => {
+          dockerApi.modem.followProgress(
+            pushStream,
+            (error: Error | null, result: any[]) => {
+              if (error) {
+                logger.debug('Failed to push docker image to target repository:', error)
+                reject(error)
+              } else {
+                // result contains an array of all the progress objects
+                logger.debug('Succesfully finished pushing docker image')
+                resolve(result)
+              }
+            },
+            () => {
+              // console.log('Progress:', obj)
+              // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
+              // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
             }
-          },
-          (obj: any) => {
-            // console.log('Progress:', obj)
-            // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
-            // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
-          })
-      })
-
-      console.log(`Successfully pushed docker image to ${dstImageName}!`)
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Failed to push docker image: ${error.message}`)
+          )
+        })
+
+        console.log(`Successfully pushed docker image to ${dstImageName}!`)
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`Failed to push docker image: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('deploy-server')
+program
+  .command('deploy-server')
   .description('deploy a game server image to target environment')
-  .argument('gameserver', 'address of gameserver (e.g. idler-develop.p1.metaplay.io)')
+  .argument('gameserver', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
   .argument('image-tag', 'docker image tag to deploy (usually the SHA of the build)')
-  .option('-s, --stack-api <stack-api-base-path>', 'explicit stack api (e.g. https://infra.p1.metaplay.io/stackapi/)')
-  .option('-f, --values <path-to-values-file>', 'path to Helm values file to use for this deployment')
-  .option('--local-chart-path <path-to-chart-directory>', 'path to local Helm chart directory (to use a chart from local disk)')
-  .option('--helm-chart-repo <url>', 'override the URL of the Helm chart repository (eg, https://charts.metaplay.dev/testing)')
-  .option('--helm-chart-version <version>', 'override the Helm chart version (eg, 0.6.0)')
+  .requiredOption('-f, --values <path-to-values-file>', 'path to Helm values file to use for this deployment')
+  .option(
+    '--local-chart-path <path-to-chart-directory>',
+    'path to local Helm chart directory (to use a chart from local disk)'
+  )
+  .option(
+    '--helm-chart-repo <url>',
+    'override the URL of the Helm chart repository (eg, https://charts.metaplay.dev/testing)'
+  )
+  .option('--helm-chart-version <version>', 'the Helm chart version to use (eg, 0.6.0)')
   .option('--deployment-name', 'Helm deployment name to use', 'gameserver')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver, imageTag, options) => {
-    try {
-      const tokens = await loadTokens()
-      const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-      const gameserverId = resolveGameserverId(gameserver, options)
-
-      console.log(`Deploying server to ${gameserver} with image tag ${imageTag}...`)
+  .action(
+    async (
+      gameserver: string | undefined,
+      imageTag: string | undefined,
+      options: {
+        organization?: string
+        project?: string
+        environment?: string
+        values: string
+        localChartPath?: string
+        helmChartRepo?: string
+        helmChartVersion?: string
+        deploymentName?: string
+      }
+    ) => {
+      try {
+        const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      // Fetch target environment details
-      const envInfo = await stackApi.getEnvironmentDetails(gameserverId)
+        console.log(`Deploying server to ${gameserver} with image tag ${imageTag}...`)
 
-      if (!imageTag) {
-        throw new Error('Must specify a valid docker image tag as the image-tag argument, usually the SHA of the build')
-      }
+        // Fetch target environment details
+        const envInfo = await targetEnv.getEnvironmentDetails()
 
-      if (!options.deploymentName) {
-        throw new Error(`Invalid Helm deployment name '${options.deploymentName}'; specify one with --deployment-name or use the default`)
-      }
-
-      // Fetch Docker credentials for target environment registry
-      const dockerCredentials = await stackApi.getDockerCredentials(gameserverId)
-
-      // Resolve information about docker image
-      // const dockerApi = new Docker({
-      //   host: dockerCredentials.registryUrl,
-      //   port: 443,
-      //   protocol: 'https',
-      //   username: dockerCredentials.username,
-      //   headers: {
-      //     Authorization: `Bearer ${dockerCredentials.password}`,
-      //     Host: dockerCredentials.registryUrl.replace('https://', ''),
-      //   }
-      // })
-      const dockerApi = new Docker()
-      const dockerRepo = envInfo.deployment.ecr_repo
-      const imageName = `${dockerRepo}:${imageTag}`
-      logger.debug(`Fetch docker image labels for ${imageName}`)
-      let imageLabels
-      try {
-        const localDockerImage = dockerApi.getImage(imageName)
-        imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
-      } catch (err) {
-        logger.debug(`Failed to resolve docker image metadata from local image ${imageName}: ${err}`)
-      }
+        if (!imageTag) {
+          throw new Error(
+            'Must specify a valid docker image tag as the image-tag argument, usually the SHA of the build'
+          )
+        }
+        // \todo validate that imageTag is just the version part (i.e, contains no ':')
 
-      // If wasn't able to resolve the images, pull image from the target environment registry & resolve labels
-      if (imageLabels === undefined) {
-        // Pull the image from remote registry
-        try {
-          console.log(`Image ${imageName} not found locally -- pulling docker image from target environment registry...`)
-          const authConfig = { username: dockerCredentials.username, password: dockerCredentials.password, serveraddress: dockerCredentials.registryUrl }
-          const pullStream = await dockerApi.pull(imageName, { authconfig: authConfig })
-
-          // Follow pull progress & wait until completed
-          logger.debug('Following image pull stream...')
-          await new Promise((resolve, reject) => {
-            dockerApi.modem.followProgress(
-              pullStream,
-              (error: Error | null, result: any[]) => {
-                if (error) {
-                  logger.debug('Failed to pull image:', error)
-                  reject(error)
-                } else {
-                  // result contains an array of all the progress objects
-                  logger.debug('Succesfully finished pulling image')
-                  resolve(result)
-                }
-              },
-              (obj: any) => {
-                // console.log('Progress:', obj)
-                // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
-                // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
-              })
-          })
-        } catch (err) {
-          throw new Error(`Failed to fetch docker image ${imageName} from target environment registry: ${err}`)
+        if (!options.deploymentName) {
+          throw new Error(
+            `Invalid Helm deployment name '${options.deploymentName}'; specify one with --deployment-name or use the default`
+          )
         }
 
-        // Resolve the labels
+        // Fetch Docker credentials for target environment registry
+        const dockerCredentials = await targetEnv.getDockerCredentials()
+
+        // Resolve information about docker image
+        // const dockerApi = new Docker({
+        //   host: dockerCredentials.registryUrl,
+        //   port: 443,
+        //   protocol: 'https',
+        //   username: dockerCredentials.username,
+        //   headers: {
+        //     Authorization: `Bearer ${dockerCredentials.password}`,
+        //     Host: dockerCredentials.registryUrl.replace('https://', ''),
+        //   }
+        // })
+        const dockerApi = new Docker()
+        const dockerRepo = envInfo.deployment.ecr_repo
+        const imageName = `${dockerRepo}:${imageTag}`
+        logger.debug(`Fetch docker image labels for ${imageName}`)
+        let imageLabels
         try {
-          logger.debug('Get docker labels again (with pulled image)')
           const localDockerImage = dockerApi.getImage(imageName)
           imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
-        } catch (err) {
-          throw new Error(`Failed to resolve docker image metadata from pulled image ${imageName}: ${err}`)
+        } catch (error) {
+          const errMessage = error instanceof Error ? error.message : String(error)
+          logger.debug(`Failed to resolve docker image metadata from local image ${imageName}: ${errMessage}`)
         }
-      }
 
-      // Try to resolve SDK version and Helm repo and chart version from the docker labels
-      // \note These only exist for SDK R28 and newer images
-      logger.debug('Docker image labels: ', JSON.stringify(imageLabels))
-      const sdkVersion = imageLabels['io.metaplay.sdk_version']
-
-      // Resolve helmChartRepo, in order of precedence:
-      // - Specified in the cli options
-      // - Specified in the docker image label
-      // - Fall back to 'https://charts.metaplay.dev'
-      const helmChartRepo = options.helmChartRepo ?? imageLabels['io.metaplay.default_helm_repo'] ?? 'https://charts.metaplay.dev'
-
-      // Resolve helmChartVersion, in order of precedence:
-      // - Specified in the cli options
-      // - Specified in the docker image label
-      // - Unknown, error out!
-      const helmChartVersion = options.helmChartVersion ?? imageLabels['io.metaplay.default_server_chart_version']
-      if (!helmChartVersion) {
-        throw new Error('No Helm chart version defined. With pre-R28 SDK versions, you must specify the Helm chart repository explicitly with --helm-chart-version.')
-      }
+        // If wasn't able to resolve the images, pull image from the target environment registry & resolve labels
+        if (imageLabels === undefined) {
+          // Pull the image from remote registry
+          try {
+            console.log(
+              `Image ${imageName} not found locally -- pulling docker image from target environment registry...`
+            )
+            const authConfig = {
+              username: dockerCredentials.username,
+              password: dockerCredentials.password,
+              serveraddress: dockerCredentials.registryUrl,
+            }
+            const pullStream = await dockerApi.pull(imageName, { authconfig: authConfig })
+
+            // Follow pull progress & wait until completed
+            logger.debug('Following image pull stream...')
+            await new Promise((resolve, reject) => {
+              dockerApi.modem.followProgress(
+                pullStream,
+                (error: Error | null, result: any[]) => {
+                  if (error) {
+                    logger.debug('Failed to pull image:', error)
+                    reject(error)
+                  } else {
+                    // result contains an array of all the progress objects
+                    logger.debug('Succesfully finished pulling image')
+                    resolve(result)
+                  }
+                },
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                (obj: any) => {
+                  // console.log('Progress:', obj)
+                  // { status: 'Preparing', progressDetail: {}, id: '82730adcaeb0' }
+                  // { status: 'Layer already exists', progressDetail: {}, id: '7cd701fff13a' }
+                }
+              )
+            })
+          } catch (error) {
+            const errMessage = error instanceof Error ? error.message : String(error)
+            throw new Error(`Failed to fetch docker image ${imageName} from target environment registry: ${errMessage}`)
+          }
+
+          // Resolve the labels
+          try {
+            logger.debug('Get docker labels again (with pulled image)')
+            const localDockerImage = dockerApi.getImage(imageName)
+            imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
+          } catch (error) {
+            const errMessage = error instanceof Error ? error.message : String(error)
+            throw new Error(`Failed to resolve docker image metadata from pulled image ${imageName}: ${errMessage}`)
+          }
+        }
 
-      // A values file is required (at least for now it makes no sense to deploy without one)
-      if (!options.values) {
-        throw new Error('Path to a Helm values file must be specified with --values')
-      }
+        // Try to resolve SDK version and Helm repo and chart version from the docker labels
+        // \note These only exist for SDK R28 and newer images
+        logger.debug('Docker image labels: ', JSON.stringify(imageLabels))
+        const sdkVersion = imageLabels['io.metaplay.sdk_version']
+
+        // Resolve helmChartRepo, in order of precedence:
+        // - Specified in the cli options
+        // - Specified in the docker image label
+        // - Fall back to 'https://charts.metaplay.dev'
+        const helmChartRepo = removeTrailingSlash(
+          options.helmChartRepo ?? imageLabels['io.metaplay.default_helm_repo'] ?? 'https://charts.metaplay.dev'
+        )
+
+        // Resolve helmChartVersion, in order of precedence:
+        // - Specified in the cli options
+        // - Specified in the docker image label
+        // - Unknown, error out!
+        const helmChartVersionSpec = options.helmChartVersion ?? imageLabels['io.metaplay.default_server_chart_version']
+        if (!options.helmChartVersion) {
+          console.warn('You should specify the Helm chart version with --helm-chart-version=<version>!')
+        }
+        if (!helmChartVersionSpec) {
+          throw new Error(
+            'No Helm chart version defined. With pre-R28 SDK versions, you must specify the Helm chart version explicitly with --helm-chart-version=<version>.'
+          )
+        }
 
-      // \If Helm chart >= 0.7.0, check that sdkVersion is defined in docker image labels (the labels were added in R28)
-      const helmChartSemver = semver.parse(helmChartVersion)
-      if (!helmChartSemver) {
-        throw new Error(`Resolve Helm chart version '${helmChartVersion}' is not a valid SemVer!`)
-      }
-      if (semver.gte(helmChartSemver, new semver.SemVer('0.7.0'), true) && !sdkVersion) {
-        throw new Error('Helm chart versions >=0.7.0 are only compatible with SDK versions 28.0.0 and above.')
-      }
+        // Parse the Helm chart version spec into a semver.Range, or null if 'latest' is specified
+        let helmChartRange: semver.Range | null = null
+        if (helmChartVersionSpec !== 'latest-prerelease') {
+          try {
+            helmChartRange = new semver.Range(helmChartVersionSpec)
+          } catch (error) {
+            throw new Error(`Helm chart version '${helmChartVersionSpec}' is not a valid SemVer range!`)
+          }
+        }
+
+        // A values file is required (at least for now it makes no sense to deploy without one)
+        if (!options.values) {
+          throw new Error('Path to a Helm values file must be specified with --values')
+        }
 
-      // Fetch kubeconfig and write it to a temporary file
-      // \todo allow passing a custom kubeconfig file?
-      const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
-      const kubeconfigPath = join(tmpdir(), randomBytes(20).toString('hex'))
-      logger.debug(`Write temporary kubeconfig in ${kubeconfigPath}`)
-      await writeFile(kubeconfigPath, kubeconfigPayload, { mode: 0o600 })
+        // Resolve available metaplay-gameserver Helm chart versions
+        const availableHelmChartVersions = await fetchHelmChartVersions(helmChartRepo, 'metaplay-gameserver')
+        logger.debug(`Available Helm chart versions: ${availableHelmChartVersions.join(', ')}`)
 
-      try {
-        // Construct Helm invocation
-        const chartNameOrPath = options.localChartPath ?? 'metaplay-gameserver'
-        const helmArgs =
-          ['upgrade', '--install', '--wait'] // \note wait for the pods to stabilize -- otherwise status check can read state before any changes to pods are applied
+        // Resolve the best matching Helm chart version
+        const resolvedHelmChartVersion = resolveBestMatchingVersion(availableHelmChartVersions, helmChartRange)
+        if (!resolvedHelmChartVersion) {
+          throw new Error(
+            `No Helm chart version found that satisfies '${helmChartVersionSpec}' in repository '${helmChartRepo}'`
+          )
+        }
+        logger.debug('Resolved Helm chart version: ', resolvedHelmChartVersion)
+
+        // Fetch kubeconfig and write it to a temporary file
+        // \todo allow passing a custom kubeconfig file?
+        const kubeconfigPayload = await targetEnv.getKubeConfigWithEmbeddedCredentials()
+        const kubeconfigPath = pathJoin(tmpdir(), randomBytes(20).toString('hex'))
+        logger.debug(`Write temporary kubeconfig in ${kubeconfigPath}`)
+        await writeFile(kubeconfigPath, kubeconfigPayload, { mode: 0o600 })
+
+        try {
+          // Construct Helm invocation
+          const chartNameOrPath = options.localChartPath ?? 'metaplay-gameserver'
+          const helmArgs = ['upgrade', '--install', '--wait'] // \note wait for the pods to stabilize -- otherwise status check can read state before any changes to pods are applied
             .concat(['--kubeconfig', kubeconfigPath])
             .concat(['-n', envInfo.deployment.kubernetes_namespace])
             .concat(['--values', options.values])
             .concat(['--set-string', `image.tag=${imageTag}`])
             .concat(sdkVersion ? ['--set-string', `sdk.version=${sdkVersion}`] : [])
-            .concat(!options.chartPath ? ['--repo', helmChartRepo, '--version', helmChartVersion] : [])
+            .concat(!options.localChartPath ? ['--repo', helmChartRepo, '--version', resolvedHelmChartVersion] : [])
             .concat([options.deploymentName])
             .concat([chartNameOrPath])
-        logger.info(`Execute: helm ${helmArgs.join(' ')}`)
-
-        // Execute Helm
-        let helmResult
-        try {
-          helmResult = await executeCommand('helm', helmArgs)
-          // \todo output something from Helm result?
-        } catch (err) {
-          throw new Error(`Failed to execute 'helm': ${err}. You need to have Helm v3 installed to deploy a game server with metaplay-auth.`)
+          logger.info(`Execute: helm ${helmArgs.join(' ')}`)
+
+          // Execute Helm
+          let helmResult
+          try {
+            helmResult = await executeCommand('helm', helmArgs)
+            // \todo output something from Helm result?
+          } catch (error) {
+            const errMessage = error instanceof Error ? error.message : String(error)
+            throw new Error(
+              `Failed to execute 'helm': ${errMessage}. You need to have Helm v3 installed to deploy a game server with metaplay-auth.`
+            )
+          }
+
+          // Throw on Helm non-success exit code
+          if (helmResult.exitCode !== 0) {
+            throw new Error(`Helm deploy failed with exit code ${helmResult.exitCode}: ${String(helmResult.stderr)}`)
+          }
+
+          const testingRepoSuffix =
+            !options.localChartPath && helmChartRepo !== 'https://charts.metaplay.dev'
+              ? ` from repo ${helmChartRepo}`
+              : ''
+          console.log(
+            `Game server deployed to ${gameserver} with tag ${imageTag} using chart version ${resolvedHelmChartVersion}${testingRepoSuffix}!`
+          )
+        } finally {
+          // Remove temporary kubeconfig file
+          await unlink(kubeconfigPath)
         }
 
-        // Throw on Helm non-success exit code
-        if (helmResult.code !== 0) {
-          throw new Error(`Helm deploy failed with exit code ${helmResult.code}: ${helmResult.stderr}`)
+        // Check the status of the game server deployment
+        try {
+          const kubeconfig = new KubeConfig()
+          kubeconfig.loadFromString(kubeconfigPayload)
+
+          console.log('Validating game server deployment...')
+          const exitCode = await checkGameServerDeployment(
+            envInfo.deployment.kubernetes_namespace,
+            kubeconfig,
+            imageTag
+          )
+          exit(exitCode)
+        } catch (error) {
+          const errMessage = error instanceof Error ? error.message : String(error)
+          console.error(`Failed to resolve game server deployment status: ${errMessage}`)
+          exit(2)
         }
-
-        const testingRepoSuffix = (!options.chartPath && helmChartRepo !== 'https://charts.metaplay.dev') ? ` from repo ${helmChartRepo}` : ''
-        console.log(`Game server deployed to ${gameserver} with tag ${imageTag} using chart version ${helmChartVersion}${testingRepoSuffix}!`)
-      } finally {
-        // Remove temporary kubeconfig file
-        await unlink(kubeconfigPath)
-      }
-
-      // Check the status of the game server deployment
-      try {
-        const kubeconfig = new KubeConfig()
-        kubeconfig.loadFromString(kubeconfigPayload)
-
-        console.log('Validating game server deployment...')
-        const exitCode = await checkGameServerDeployment(envInfo.deployment.kubernetes_namespace, kubeconfig)
-        exit(exitCode)
       } catch (error) {
-        console.error(`Failed to resolve game server deployment status: ${error}`)
-        exit(2)
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error deploying game server into target environment: ${error.message}`)
+        if (error instanceof Error) {
+          console.error(`Error deploying game server into target environment: ${error.message}`)
+        }
+        exit(1)
       }
-      exit(1)
     }
-  })
+  )
 
-program.command('check-server-status')
-  .description('check the status of a deployed server and print out information that is helpful in debugging failed deployments')
+program
+  .command('check-server-status')
+  .description(
+    'check the status of a deployed server and print out information that is helpful in debugging failed deployments'
+  )
   .argument('[gameserver]', 'address of gameserver (e.g. metaplay-idler-develop or idler-develop.p1.metaplay.io)')
   .hook('preAction', async () => {
     await extendCurrentSession()
   })
-  .action(async (gameserver: string | undefined, options) => {
-    const tokens = await loadTokens()
-    const stackApi = new StackAPI(tokens.access_token, options.stackApi)
-    const gameserverId = resolveGameserverId(gameserver, options)
-
-    try {
-      logger.debug('Get environment info')
-      const envInfo = await stackApi.getEnvironmentDetails(gameserverId)
-      const kubernetesNamespace = envInfo.deployment.kubernetes_namespace
+  .action(
+    async (
+      gameserver: string | undefined,
+      options: { organization?: string; project?: string; environment?: string }
+    ) => {
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
 
-      // Load kubeconfig from file and throw error if validation fails.
-      logger.debug('Get kubeconfig')
-      const kubeconfig = new KubeConfig()
       try {
-        // Fetch kubeconfig and write it to a temporary file
-        // \todo allow passing a custom kubeconfig file?
-        const kubeconfigPayload = await stackApi.getKubeConfig(gameserverId)
-        kubeconfig.loadFromString(kubeconfigPayload)
-      } catch (error) {
-        throw new Error(`Failed to load or validate kubeconfig. ${error}`)
-      }
+        logger.debug('Get environment info')
+        const envInfo = await targetEnv.getEnvironmentDetails()
+        const kubernetesNamespace = envInfo.deployment.kubernetes_namespace
 
-      // Run the checks and exit with success/failure exitCode depending on result
-      console.log(`Validating game server deployment in namespace ${kubernetesNamespace}`)
-      const exitCode = await checkGameServerDeployment(kubernetesNamespace, kubeconfig)
-      exit(exitCode)
-    } catch (error: any) {
-      console.error(`Failed to check deployment status: ${error.message}`)
-      exit(1)
+        // Load kubeconfig from file and throw error if validation fails.
+        logger.debug('Get kubeconfig')
+        const kubeconfig = new KubeConfig()
+        try {
+          // Initialize kubeconfig with the payload fetched from the cloud
+          // \todo allow passing a custom kubeconfig file?
+          const kubeconfigPayload = await targetEnv.getKubeConfigWithEmbeddedCredentials()
+          kubeconfig.loadFromString(kubeconfigPayload)
+        } catch (error) {
+          const errMessage = error instanceof Error ? error.message : String(error)
+          throw new Error(`Failed to load or validate kubeconfig. ${errMessage}`)
+        }
+
+        // Run the checks and exit with success/failure exitCode depending on result
+        console.log(`Validating game server deployment in namespace ${kubernetesNamespace}`)
+        // \todo Get requiredImageTag from the Helm chart
+        const exitCode = await checkGameServerDeployment(kubernetesNamespace, kubeconfig, /* requiredImageTag: */ null)
+        exit(exitCode)
+      } catch (error: any) {
+        console.error(`Failed to check deployment status: ${error.message}`)
+        exit(1)
+      }
     }
-  })
+  )
 
-program.command('check-deployment')
-  .description('[deprecated] check that a game server was successfully deployed, or print out useful error messages in case of failure')
+program
+  .command('check-deployment')
+  .description(
+    '[deprecated] check that a game server was successfully deployed, or print out useful error messages in case of failure'
+  )
   .argument('[namespace]', 'kubernetes namespace of the deployment')
   .action(async (namespace: string) => {
-    console.error('DEPRECATED! Use the "metaplay-auth check-server-status [gameserver]" command instead! This command will be removed soon.')
+    console.error(
+      'DEPRECATED! Use the "metaplay-auth check-server-status [gameserver]" command instead! This command will be removed soon.'
+    )
 
     try {
       if (!namespace) {
@@ -673,12 +972,14 @@ program.command('check-deployment')
       try {
         kubeconfig.loadFromFile(kubeconfigPath)
       } catch (error) {
-        throw new Error(`Failed to load or validate kubeconfig. ${error}`)
+        const errMessage = error instanceof Error ? error.message : String(error)
+        throw new Error(`Failed to load or validate kubeconfig: ${errMessage}`)
       }
 
       // Run the checks and exit with success/failure exitCode depending on result
       console.log(`Validating game server deployment in namespace ${namespace}`)
-      const exitCode = await checkGameServerDeployment(namespace, kubeconfig)
+      // \todo Get requiredImageTag from the Helm chart
+      const exitCode = await checkGameServerDeployment(namespace, kubeconfig, /* requiredImageTag: */ null)
       exit(exitCode)
     } catch (error: any) {
       console.error(`Failed to check deployment status: ${error.message}`)
@@ -686,4 +987,29 @@ program.command('check-deployment')
     }
   })
 
+program
+  .command('debug-server')
+  .description('run an ephemeral debug container against a game server pod running in the cloud')
+  .argument('gameserver', 'address of gameserver (e.g., metaplay-idler-develop or idler-develop.p1.metaplay.io)')
+  .argument('[pod-name]', 'name of the pod to debug (must be specified if deployment has multiple pods)')
+  .hook('preAction', async () => {
+    await extendCurrentSession()
+  })
+  .action(
+    async (
+      gameserver: string,
+      podName: string | undefined,
+      options: { organization?: string; project?: string; environment?: string }
+    ) => {
+      // Resolve target environment
+      const targetEnv = await resolveTargetEnvironment(gameserver, options)
+
+      // Exec 'kubectl debug ...'
+      await debugGameServer(targetEnv, podName)
+    }
+  )
+
+// Register docker build command
+registerBuildCommand(program)
+
 void program.parseAsync()