AccelByte Gaming Services (AGS) is a fully-managed game backend for online games and has 24 active API services. For the past few years, the practical ways to work with them have been the Admin Portal, the AccelByte SDKs, or raw API calls with curl or a REST client. That covers most of the day-to-day.
But there was no unified command surface for developers to script setup, automate a QA pipeline, run a one-off investigation without opening a browser, or give an AI agent a reliable way to call backend APIs.
That is exactly the gap AGS CLI fills and the first version is now live!
Before getting into how the CLI works, it is worth covering what we are building toward because the design decisions in v1 only make sense in that context. For the full architecture picture, the AGS Client Runtime, the AI Marketplace plugin, and how every developer surface connects to AGS, see Beyond the Chat Box by Phil Tossell.
The goal is a terminal-native operations layer for AccelByte Gaming Services. Everything you can do in the Admin Portal, you can do from the terminal. And once it is in the terminal, you can compose it, script it, version-control it, and hand it to an AI agent.
Here is what our roadmap looks like:
Now - individual operations. Every AGS API, from the terminal, across all 24 services. That is what this release is.
Next - workflows. Sequenced operations that run as a unit. create and configure a new authentication method, set up matchmaking with AMS, configure and populate a new store, seed test data - as a single command, not a checklist. This is where automation and AI use cases go from convenient to genuinely powerful. The workflow format is already published as an open spec: read the workflow definition spec (v1.0).
After that - an in-terminal UI. Switching to a browser to check something that could be rendered in your terminal is a context switch that adds up. The goal is to stay in the environment you are already in.
In progress now - AGS setup integration. The first steps of configuring a new AGS environment, the ones you currently do through the portal, will be doable from the terminal.
Alongside the CLI, AccelByte also ships MCP servers for AGS, Extend, and Unreal integration. These give AI coding assistants like Claude direct, structured access to AccelByte's API surface and Extend SDK.
AGS MCP server - covers AccelByte Gaming Services APIs. An AI assistant can query, create, and manage AGS resources directly through the MCP tool interface. Get the AGS API MCP server.
Extend MCP server - covers AccelByte Extend. Developers building custom game logic on top of AGS can use this with an AI assistant to scaffold, validate, and iterate on service extensions without leaving their editor. Get the AGS Extend SDK MCP server.
Unreal MCP server - assists with integrating AGS into Unreal Engine.
AI Marketplace plugin - the glue layer that connects AI hosts (Claude Code, Codex, IDE assistants) to both the CLI and MCP servers. It handles workflow discovery, intent routing, and surfacing confirmation steps in whatever form the host's interface understands. Get the AI Marketplace plugin.
Developers can use them to write production-ready backend code without having to manually trace through API documentation, understand request schemas, or figure out how Extend service extensions are structured. The MCP server injects the right context automatically.
More on how both work: AccelByte MCP servers give AI assistants real backend context.
The CLI and MCP servers are complementary, but they serve different purposes. MCP gives AI assistants structured access to AGS so they can understand APIs and generate the correct code. The CLI is the execution layer: it's how you run those operations directly and integrate them into scripts, CI pipelines, and operational workflows. In practice, if you're building on AGS with an AI coding assistant, you'll likely use both: MCP for code generation and guidance, and the CLI for execution and automation.
The CLI is built in Rust and generates its command tree directly from AccelByte's OpenAPI 2.0 specifications - all 24 of them, covering every AGS service.
The commands are not a hand-written wrapper around a subset of the API. They are derived from the same specs that define the API itself - every supported operation, every parameter, every field. When the specs update, the CLI updates with them. The practical consequence: the CLI always covers the full API surface, by construction, rather than by someone maintaining a separate layer of bindings.
Under the hood, the CLI sits on top of the AGS Client Runtime - the unified layer that sits behind every interface, from the terminal to AI hosts. This is why a developer logs in once with ags auth login and every surface wired into the Runtime inherits that session. It also means that commands you run interactively, in CI, or through an AI agent are all going through the same underlying layer.
Phil covers the full architecture in Beyond the Chat Box.
This is the same philosophy behind AccelByte CodeGen, which generates SDK clients from the same OpenAPI specs. The CLI is the operational interface built on the same foundation. Installing it is one step: download the prebuilt binary for your OS and architecture from the releases page, put it on your PATH
ags --help
No runtime dependency. No Node or Python version to manage. Supported on macOS, Linux, and Windows.
Commands follow a consistent shape across every service:
ags <service> <resource> <method> [flags]
There are three modes depending on how you are working:
|
Interactive |
Automation |
AI Agent |
|
|
Auth |
Browser login |
Client credentials |
Either |
|
Key flags |
--dry-run, --skeleton |
--no-input, --yes, --format json |
--no-input, --format json, --dry-run |
|
Best for |
Local debugging, one-off ops |
CI pipelines, scripts, data exports |
AI-assisted backend operations |
Log in once, run commands directly. This is the right mode for local development and investigation work: checking player state, reviewing session data, running one-off admin operations without touching the portal.
ags auth login
ags iam users search --namespace my-game
ags session game-sessions get \
--namespace my-game \
--session-id abc-123 \
--api-scope public --api-version v1
The login flow opens a browser window and completes through a localhost callback. After that, the session is stored in your OS keychain and reused until the token expires and because it goes through the AGS Client Runtime, it is shared across every surface wired into it: the CLI, the MCP servers, and any AI host using the AI Marketplace plugin. Log in once, and it carries. Output is formatted for reading by default -- colour, aligned columns. A few flags worth knowing for interactive use:
--help works at every level of the command tree (ags iam --help, ags iam users --help, and so on).
--skeleton prints a starter request body template for operations that take JSON input.
--dry-run shows exactly what the CLI would send without sending it.
For scripts and CI, turn off interactive behaviour and switch to stable machine-readable output. Three flags cover most of it:
--no-input -- fail rather than prompt when something is missing.
--yes -- auto-confirm mutating operations without prompting.
--format json -- structured output that pipes cleanly into jq or any program.
For headless environments, use client credentials and inject them from your secret manager at runtime:
export AGS_BASE_URL="https://your-deployment.accelbyte.io" export AGS_CLIENT_ID="your-client-id" export AGS_CLIENT_SECRET="your-client-secret" ags auth login --grant client-credentials --no-input ags platform entitlements list \ --namespace my-game \ --user-id abc-123 \ --api-scope admin --api-version v1 \ --no-input --yes --format json
One thing worth calling out: always pin --api-scope and --api-version in automation. Without --api-version, the CLI resolves to the latest stable version it knows about, which can shift when you upgrade the binary. Use ags describe <service> <resource> <method> to check the full scope and version matrix for any command before pinning.
This is where the design choices in the CLI are most deliberate. The CLI was built to support AI agent access from the start, not retrofitted for it. Two things make it work well:
ags describe as a grounding mechanism. Before an agent calls anything, it needs to know what commands exist, what parameters they take, and what the stable contract is. ags describe returns this as machine-readable JSON -- the exact schema, without the noise of a full OpenAPI spec dump. The agent confirms what a command does before running it, rather than guessing.
--format json as the stable output contract. Human-readable output is not a contract -- wording and layout can change between releases. JSON output is. Fields will not be removed or renamed without a major version bump, which makes output parsing reliable across CLI updates.
In practice, a well-behaved agent interaction follows three steps:
# 1. Inspect the command schema ags describe session game-sessions get # 2. Dry-run to verify the request before sending ags session game-sessions get \ --namespace my-game \ --session-id abc-123 \ --api-scope public --api-version v1 \ --format json --dry-run # 3. Execute ags session game-sessions get \ --namespace my-game \ --session-id abc-123 \ --api-scope public --api-version v1 \ --format json
For operations that require a request body, --skeleton generates a template the agent can populate before executing. If the agent is running as the same OS user on the same machine, it reuses the developer's existing session automatically. Running in a container or CI runner? Authenticate it explicitly with client credentials instead.
The CLI uses OAuth2 and requires an IAM client from the AccelByte Admin Portal under Platform Configuration → IAM Clients. Which type you need depends on how you are using it:
| Client Type |
When to Use |
Required Setup |
|
Public |
Interactive, local development |
Add http://127.0.0.1:8080/ as a redirect URI |
|
Confidential |
CI, headless, automation |
Note the client secret for injection at runtime |
One gotcha for private cloud deployments: Google SSO requires a publisher-level IAM client. A game-level client will fail at the Google login redirect because Google SSO is configured at the publisher level, not the game namespace level. Use a publisher-level client for SSO, or a game-level client with email and password.
Profiles keep separate credentials and config for different environments. A default profile is created automatically -- for single-environment use you do not need to think about this at all.
For teams across dev, staging, and production: ags profile create <name> creates a new profile, ags profile use <name> switches to it, and --profile <name> targets a specific profile for a single command without switching. Each profile stores its own base URL, client ID, namespace, and credentials independently.
Run ags doctor. It checks your config, auth state, and connectivity and tells you what is wrong.
ags doctor # full check ags doctor --offline # skip network checks ags doctor --all # check all profiles
AGS in a shared cloud environment is completely free during development and comes with a 90-day free trial if you’re already live.
Sign up and start using the CLI →
The CLI is open source and available at github.com/AccelByte/accelbyte-ags-cli. Download the binary, put it on your PATH, and run ags --help to get started. Install instructions, the full service list, and the contributing guide are in the README.
Want to walk through the integration for your specific setup? Talk to us →