AGS CLI for Extend

Last updated on October 29, 2026

Overview

Use the AGS CLI for current Extend work. The Extend Helper CLI is deprecated. Its page is kept as a historical reference, including the end-of-support date.

Install and sign-in steps are in Install and sign in. A command-by-command map from the old CLI is in Migrate from extend-helper-cli.

Prerequisites

1. Docker (Docker Desktop 4.30+ / Docker Engine v23.0+)

   • For Linux:

     1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.

     2. Add your user to the docker group: sudo usermod -aG docker $USER.

     3. Log out and log back in to allow the changes to take effect.

   • For Windows/macOS:

     Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

     docker version
     
     ...
     Server: Docker Desktop
        Engine:
        Version:          24.0.5

2. Access to an AGS environment. Take note of the Base URL.

   • Example for AGS Public Cloud: https://spaceshooter.prod.gamingservices.accelbyte.io

   • Example for AGS Private Cloud: https://dev.customer.accelbyte.io

3. Create a confidential IAM client with the following permissions. To create the client, see Manage access control for applications. Write down the Client ID and Client Secret.

   • For AGS Private Cloud, add these permissions:

     1. ADMIN:NAMESPACE:{namespace}:EXTEND:APP [CREATE, READ, UPDATE, DELETE]
     2. ADMIN:NAMESPACE:{namespace}:EXTEND:DEPLOYMENT [CREATE]
     3. ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
     4. ADMIN:NAMESPACE:{namespace}:EXTEND:SECRET [CREATE, READ, UPDATE]
     5. ADMIN:NAMESPACE:{namespace}:EXTEND:VARIABLE [CREATE, READ, UPDATE]
     6. ADMIN:NAMESPACE:{namespace}:EXTEND:IMAGE [READ]

   • For AGS Public Cloud, tick these permission groups:

     1. Extend > App Management: Read, Create, Update, Delete
     2. Extend > Configuration Secret Management: Read, Create, Update
     3. Extend > Configuration Variable Management: Read, Create, Update
     4. Extend > Deployment Management: Create
     5. Extend > Extend app image repository access: Read
   warning

   For AGS Public Cloud users: Create a dedicated OAuth client exclusively for the AGS CLI with only the permissions listed above. If you use an OAuth client with too many permissions, HTTP requests from the CLI may be rejected by the server due to "Request Header or Cookie Too Large" errors.

4. Install the AGS CLI. Follow Install and sign in.

Setup

The AGS CLI does not read a .env file. Configure credentials with environment variables, or pass them to ags auth login.

Export the values from your terminal (replace the placeholders with your credentials):

export AGS_BASE_URL=<your_base_url>
export AGS_CLIENT_ID=<your_client_id>
export AGS_CLIENT_SECRET=<your_client_secret>

Optional:

• AGS_ACCESS_TOKEN — use an existing bearer token instead of a client secret.
• AGS_NAMESPACE — default namespace when you omit --namespace.

These are not the AB_* variables used by the Extend Helper CLI.

Sign in once per session:

ags auth login

For a script or CI job, sign in with a confidential IAM client:

ags auth login --grant client-credentials --no-input

--namespace (-n) is a global flag. --yes (-y) skips confirmation prompts. --confirm from the Extend Helper CLI is not accepted.

Usage

To list Extend subcommands:

ags extend --help

Create an Extend app

Use create-app with a JSON body. The scenario goes in --json, not as a --scenario flag.

ags extend create-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"scenario":"service-extension"}' --yes

Available scenario values:

• function-override
• service-extension
• event-handler

Sample response

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "",
  "appRepoUrl": "",
  "basePath": "xxx-xxxx-xxxx",
  "CPU": {
    "cpuLimit": 1550,
    "requestCPU": 1000
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "deletedAt": "",
  "deploymentCreatedAt": "",
  "deploymentId": "",
  "deploymentImageTag": "",
  "memory": {
    "memoryLimit": 3300,
    "requestMemory": 350
  },
  "message": "",
  "replica": {
    "maxReplica": 10,
    "minReplica": 1,
    "replicaLimit": 60
  },
  "scenario": "service-extension",
  "servicePublicURL": "https://xxxx.accelbyte.io/xxx-xxxx-xxxx",
  "serviceURL": "",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

You can use --wait with --wait-interval <seconds> (default: 10) and --wait-limit <seconds> (default: 600) to wait until the app is ready for image upload or deployment.

ags extend create-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"scenario":"service-extension"}' --yes --wait

Get Extend app information

Use get-app-info to get details for one Extend app:

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app>

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "arn:aws:ecr:xxxxxxxxx:xxxxxxxxxxxx:xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appRepoUrl": "xxxx.xxxx.xxxx.xxxxxxxxx.xxxx.xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appStatus": "app-undeployed",
  "app_release_status": "U",
  "basePath": "xxx-xxxx-xxxx",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "scenario": "service-extension",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

get-app-info has no --path flag. Use --format json and read the field you need:

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app> --format json | jq -r .appName

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app> --format json | jq -r .appRepoUrl

Getting credentials to push an Extend app container image

Use docker-login to sign Docker in to the Extend app container registry for one namespace and app:

ags extend docker-login --namespace <my-game-namespace> --app <my-extend-app>

Sample response

Login Succeeded

warning

The credentials are scoped to that game namespace and Extend app. For a different namespace or app, run docker-login again.

If docker-login fails, see Docker login fails.

Push an Extend app container image

image-upload builds the container image, tags it, and pushes it to the Extend app container registry.

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile>

--app and --image-tag are required. Optional flags include --dockerfile, --platform, --work-dir, --retry-limit, --retry-interval, and --retry-rate.

Pass --login to authenticate to the registry before the build so you do not need a separate docker-login step:

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile> \
    --login

If the upload fails, use --retry-limit (with optional --retry-interval and --retry-rate) to retry:

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile> \
    --retry-limit 3

Create and update Extend app environment variables and secrets

Use update-var to create or update an environment variable:

ags extend update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100

Use update-secret to create or update a secret:

ags extend update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>

Pass --force to create the variable or secret when --key does not already exist:

ags extend update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100 --force

ags extend update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key> --force

Prefer --value-stdin over --value so the value does not appear in shell history.

List Extend app container images

Use list-images to list the container images for one Extend app. The IAM client needs ADMIN:NAMESPACE:{namespace}:EXTEND:IMAGE [READ].

ags extend list-images --namespace <my-game-namespace> --app <my-extend-app>

--cached defaults to true. Pass --cached false to skip the cache.

Deploy an Extend app

Use deploy-app with a JSON body. The image tag goes in --json, not as an --image-tag flag on this command.

ags extend deploy-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"imageTag":"v1.0.0"}'

Sample response

{
  "deploymentId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Add --wait (and optional --wait-interval / --wait-limit) to wait until deployment finishes:

ags extend deploy-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"imageTag":"v1.0.0"}' --wait

Start and stop an Extend app

ags extend start-app --namespace <my-game-namespace> --app <my-extend-app>

ags extend stop-app --namespace <my-game-namespace> --app <my-extend-app>

You can use --wait with --wait-interval <seconds> (default: 10) and --wait-limit <seconds> (default: 600):

ags extend start-app --namespace <my-game-namespace> --app <my-extend-app> --wait

ags extend stop-app --namespace <my-game-namespace> --app <my-extend-app> --wait

Delete an Extend app

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes

Pass --forced true to delete the app regardless of its current status (default: false).

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes --forced true

You can use --wait with --wait-interval and --wait-limit to wait until deletion finishes:

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes --wait

Stream Extend app logs

logs stream requires AGS CLI 0.5.2 or later. Without --follow, the command prints recent lines and exits. With --follow, it keeps printing new lines until you press Ctrl-C.

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app>

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app> --follow

Useful flags:

• --tail-lines <n> (alias --tail) — recent lines per pod (default: 100)
• --pods <count> — pods to stream from (default: 1)
• --since-seconds <seconds> — only lines newer than this
• --previous — previous container instance (crash text after a restart)

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app> --tail-lines 200 --previous

For Admin Portal log cards and historical download, see View Extend app logs.

Open a database tunnel

database-tunnel requires AGS CLI 0.5.3 or later. It binds a local TCP port to an Extend database resource until you press Ctrl-C.

ags extend database-tunnel --namespace <my-game-namespace> --resource-name <resource-name> --local-port <port>

See the Extend database guides for resource names and connection examples:

• NoSQL
• SQL
• Key-value store

Remote debug an Extend app

Use remote-debug to enable, connect to, or disable a debug session on a running app. Full steps are in Local debugging — with remote live traffic.

ags extend remote-debug enable --namespace <my-game-namespace> --app <my-extend-app> --yes

ags extend remote-debug connect --namespace <my-game-namespace> --app <my-extend-app>

ags extend remote-debug disable --namespace <my-game-namespace> --app <my-extend-app> --yes

Pass --yes to skip the confirmation prompt when enable or disable restarts a running app.

Clone a starter template

ags extend clone-template --template "<full-template-name>" --destination <dir>

clone-template has no --scenario flag. --template takes the full template name, such as Extend App UI :: react :: JavaScript, not a short name like react. If the name does not match, the command prints every available template name. Without --template, the command asks you to choose a scenario, template, and language.

Extend App UI

ags extend app-ui create --namespace <my-game-namespace> --json '{"name":"<app-ui-name>"}'
ags extend app-ui setup-env --namespace <my-game-namespace> --name <app-ui-name>
ags extend app-ui upload --namespace <my-game-namespace> --name <app-ui-name>

app-ui create sends name in the JSON body. setup-env and upload take --name.

Request a security assessment

The security-assessment commands are documented in Request a security assessment.

Troubleshooting

Docker login fails

ags extend docker-login or ags extend image-upload --login returns the following error:

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

The Extend registry token is larger than most Docker credential helpers can store. For more information, see Docker's credential helper issue.

On native Windows, skip the credential helper. Print the token and pass it to docker login yourself. For the full command, see Docker login on Windows.

On Linux or WSL2, remove the credential helper from your Docker configuration:

Linux

1. Remove "credsStore": "desktop.exe" from $HOME/.docker/config.json.
2. Run ags extend docker-login again.

Windows (WSL2)

1. In the Windows file system:

   • Remove "credsStore": "desktop.exe" from %USERPROFILE%\.docker\config.json.
   • Rename the following files in C:\Program Files\Docker\Docker\resources\bin:
     • docker-credential-desktop.exe to docker-credential-desktop.exe.old
     • docker-credential-wincred.exe to docker-credential-wincred.exe.old

2. In the WSL2 file system, remove "credsStore": "desktop.exe" from $HOME/.docker/config.json.

3. Run ags extend docker-login again.

note

You may have to apply this workaround again. Docker Desktop can restore "credsStore": "desktop" in config.json when it restarts. For more information, see Docker's config.json issue.