Install AgileBuilder

Requirements

Before installing the AgileBuilder CLI, make sure your system has:

• Node.js 20.0.0 or later (the CLI's engines field requires node >= 20.0.0)
• Git: templates are distributed as Git repositories, so Git must be available when creating projects
• Any package manager: npm (bundled with Node.js), pnpm, or yarn

Check your environment:

node --version   # must be >= v20.0.0
git --version

Install the CLI

Install globally via npm:

npm install -g agilebuilder

The package provides three executables:

Command	Description
agilebuilder	The main CLI command
ag	A short alias for agilebuilder; the two are fully equivalent
agilebuilder-mcp	The MCP stdio server, configured into AI tools

You can also run it without installing via npx (handy for CI or one-off use):

npx agilebuilder --help
npx agilebuilder@latest create --git-url <url> --target ./app

Verify the installation

ag --version    # prints the version, e.g. 1.2.2
ag --help       # lists all commands

ag --help should show these commands: config, login, logout, auth, space, res, create, device.

Choose a backend region

The backend.profile config key controls which regional cloud service the CLI talks to:

Value	Behavior
auto (default)	Picks the China region when the system locale/timezone indicates mainland China, otherwise the Global region
china	Uses the *.agilebuilder.cn endpoints
global	Uses the *.agilebuilder.net endpoints

ag config list                          # show current config
ag config set backend.profile global    # set the region manually
ag config set language en-US            # CLI output language: auto / zh-CN / en-US

Data directory

The CLI stores its local data in:

~/.agilebuilder/v2

Main files:

File	Purpose
config.json	CLI configuration
current-space.json	The currently selected workspace
resources/local.json	Local template and doc resources
auth.enc	Encrypted authentication credentials

You can override the data directory with the AGILEBUILDER_CORE1_DATA_DIR environment variable:

AGILEBUILDER_CORE1_DATA_DIR=/tmp/ag-data ag res list

Upgrade and uninstall

Upgrade to the latest version:

npm install -g agilebuilder@latest

Uninstall:

npm uninstall -g agilebuilder

Next steps

• Quickstart · Open Source — generate your first project locally, no account needed
• Quickstart · Pro — sign in and use cloud spaces
• CLI Reference — every command and option in detail