AgileBuilder CLI is a Git-template-based project scaffolding and development resource management tool. Once installed, it provides the agilebuilder command (short alias ag; the two are fully equivalent) plus the agilebuilder-mcp MCP server process.

Package name: agilebuilder
Runtime: Node.js >=20.0.0

npm install -g agilebuilder

You can also run it without installing (handy for CI and AI agents):

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

Global Usage

agilebuilder [options] [command]
ag [options] [command]

Option	Description
`-V, --version`	Print the version number.
`-h, --help`	Show help.
`help [command]`	Show help for a specific command.

Command Overview

Command	Description
`config`	Manage CLI configuration.
`login`	Log in with OAuth or an API key.
`logout`	Clear local authentication.
`auth status`	Show authentication status.
`auth require-token`	Require a usable token; fails with a non-zero exit code otherwise.
`space list` / `space ls`	List local and Cloud workspaces.
`space current`	Show the current workspace.
`space use <workspace>`	Select `local` or a Cloud workspace ID.
`res list` / `res ls`	List resources.
`res search <keyword>`	Search resources.
`res get <id>`	Show resource details.
`res add template`	Add a template resource.
`res add doc`	Add a document resource.
`res edit <id>`	Edit a resource.
`res remove <id>` / `res rm <id>`	Remove a resource.
`create [resource-id]`	Create a project from a resource or a Git URL.
`device list` / `device ls`	List registered devices.
`device revoke <device-id>`	Revoke a single device.
`device revoke-all`	Revoke every device except the current one.

res can also be written as resource. For the full resource workflow, see Resource Management.

config: CLI Configuration

ag config list
ag config get backend.profile
ag config set backend.profile global

Supported configuration keys (any other key is rejected):

Key	Values	Default	Description
`backend.profile`	`auto`, `china`, `global`	`auto`	Backend endpoint selection. `china` uses `.agilebuilder.cn` (`www`, `api-auth`, `api-app`); `global` uses `.agilebuilder.net`. `auto` picks the China region when the locale or timezone indicates mainland China, and the global region otherwise.
`language`	`auto`, `zh-CN`, `en-US`	`auto`	CLI output language. When set to `auto`, the CLI reads `AGILEBUILDER_LANG`, `LC_ALL`, `LC_MESSAGES`, and `LANG` in order.
`template.allowHooksDefault`	`true`, `false`	`false`	Default hook authorization when `create` is run without `--allow-hooks`. An explicit `--allow-hooks` flag always takes precedence.

Values passed to config set are parsed as scalars: true/false become booleans, numbers become numbers, and everything else stays a string.

Cloud resources, Cloud workspaces, license refresh, and device management all require login.

OAuth login (the default):

ag login

The CLI opens your browser and listens for the OAuth callback on 127.0.0.1. It starts at port 51280 and probes up to 10 consecutive ports; if all are taken it fails with OAUTH_PORT_UNAVAILABLE.

API key login:

ag login --api-key <key>

Inspect and clear authentication state:

ag auth status          # Show login state, auth type, and user info
ag auth require-token   # Fails with AUTH_TOKEN_UNAVAILABLE when no valid token exists; useful as a pre-flight check in scripts
ag logout               # Clear locally stored credentials

All three support --json. OAuth tokens are refreshed automatically whenever possible; an API key stays as the current credential until you run logout.

space: Workspaces

AgileBuilder ships with a built-in local workspace (local, no login required); after login you can also use AgileBuilder Cloud workspaces. The current workspace affects resource commands and how create <resource-id> resolves resources.

ag space list            # List local and Cloud workspaces (supports --refresh to reload the cloud cache, and --json)
ag space current         # Show the current workspace
ag space use local       # Switch back to the local workspace
ag space use <space-id>  # Switch to a Cloud workspace

Resource write commands target the current workspace by default. You can also pass --space-id <id> to target a specific workspace for one command without switching.

res: Resource Management

There are two resource types: template (a pointer to a Git repository, used by create) and doc (Markdown or plain-text documents). Only the syntax is listed here; see Resource Management for the full workflow.

ag res list [--type template|doc] [--space-id <id>] [--json]
ag res search <keyword> [--type template|doc] [--space-id <id>] [--json]
ag res get <id> [--json]

--space-id targets a specific Cloud workspace for the operation (supported by list/search and add/edit/remove). The local workspace is a flat list with no folder tree; --parent-id is Cloud-only.

Add a template resource (--name and --git-url are required; --branch defaults to main):

ag res add template \
  --name service-template \
  --git-url https://github.com/example/service-template.git \
  --branch main \
  --subdir templates/node \
  --description "Node.js service starter" \
  --tags "node,service"

Add a document resource (at least one of --file or --content is required):

ag res add doc \
  --name architecture-notes \
  --file ./docs/architecture.md \
  --format markdown \
  --tags "docs,architecture"

Document resource options: --uri <uri> (local docs default to local-doc://<name>), --format <format> (markdown or text, default markdown).

Edit and remove:

ag res edit <id> --name new-name --description "Updated"
ag res edit <doc-id> --file ./README.md --format markdown
ag res remove <id> --yes

Edit validation rules: at least one editable field is required; --file and --content are mutually exclusive; template-only fields (--git-url, --branch, --subdir) cannot be used on document resources, and document-only fields (--uri, --file, --content, --format) cannot be used on template resources. Removal always requires an explicit --yes.

create: Creating Projects

Create directly from a Git URL, or from a template resource in the current workspace:

ag create --git-url https://github.com/example/template.git --target ./app
ag create <resource-id> --target ./app

Options:

Option	Required	Description
`[resource-id]`	Not when `--git-url` is used	Must point to a template resource; pointing at a document resource fails with `CREATE_REQUIRES_TEMPLATE`.
`--git-url <url>`	Not when a resource ID is used	Create directly from a Git repository (shallow clone, `--depth 1`).
`--branch <branch>`	No	Override the resource branch, or pick the branch for a direct Git clone.
`--subdir <path>`	No	Override the resource subdirectory, or pick a template subdirectory inside the repository.
`--target <dir>`	Yes	Output directory.
`--vars <path>`	No	A JSON file containing a single object of template variables.
`--var <key=value...>`	No	One or more scalar variable assignments.
`--overwrite`	No	Allow writing into a non-empty target directory.
`--keep-git`	No	Keep the template repository's `.git` directory; skipped by default.
`--allow-hooks`	No	Allow template hooks; takes precedence over `template.allowHooksDefault`.
`--interactive`	No	Prompt for missing template variables interactively. Requires a TTY and cannot be combined with `--json`.
`--json`	No	Output JSON.

Variable precedence (--vars file > --var flags; remaining variables fall back to the defaults from the template configuration, and interactive prompts only fill in whatever is still missing):

Variables from the --vars <path> file.
Repeated --var key=value assignments (override same-named variables from --vars).
Defaults from the template's inquirerQuestions, applied only while a variable is still missing.
--interactive prompts, which only fill in variables that are still missing.

--var parses true, false, null, and numbers into their scalar types; everything else stays a string.

Target directory safety rules:

The CLI refuses to write to system directories (drive roots, C:\Windows, C:\Program Files, and similar), failing with UNSAFE_TARGET_DIR.
An existing non-empty directory requires an explicit --overwrite, otherwise the command fails with TARGET_NOT_EMPTY.
A missing target directory is created automatically.

device: Device Management

Device commands require login:

ag device list                                  # List registered devices
ag device revoke <device-id> --reason "No longer used"
ag device revoke-all                            # Revoke every device except the current one

All support --json.

JSON Output Protocol

Every command marked as supporting --json follows the same structured output protocol, designed for scripts and AI agents.

On success, stdout receives:

{
  "ok": true,
  "data": {}
}

On failure, stderr receives the payload below and the process exits with code 1:

{
  "ok": false,
  "error": {
    "code": "TEMPLATE_VARS_MISSING",
    "message": "Missing required template variables: appName",
    "suggestion": "Pass values with --vars or --var key=value, or use --interactive to enter them interactively.",
    "category": "validation"
  }
}

error.category is one of auth, permission, network, validation, resource, system. The suggestion field carries an actionable fix and is a key part of the AI-agent-friendly design. Without --json, errors are printed as human-readable text.

Common Error Codes

Code	Meaning and suggested fix
`CREATE_SOURCE_REQUIRED`	Neither a resource ID nor `--git-url` was provided.
`CREATE_REQUIRES_TEMPLATE`	The resource ID passed to `create` points to a document resource.
`TEMPLATE_VARS_MISSING`	Required template variables are missing; supply them with `--var`, `--vars`, or `--interactive`.
`TEMPLATE_VARS_FILE_INVALID`	The `--vars` file does not exist, is unreadable, or is not a single JSON object.
`TEMPLATE_VAR_INVALID`	A `--var` assignment is malformed; use `key=value`.
`TEMPLATE_CONFIG_INVALID`	The template config file is not valid YAML/JSON.
`TEMPLATE_SUBDIR_UNSAFE`	`--subdir` is an absolute path or contains `..`, escaping the template directory.
`UNSAFE_TARGET_DIR`	The target directory is a system directory or drive root.
`TARGET_NOT_EMPTY`	The target directory is non-empty and `--overwrite` was not passed.
`TARGET_NOT_WRITABLE`	The target path exists and is not a directory.
`HOOK_TYPE_UNSUPPORTED`	The hook's `scriptType` is not `shell`.
`HOOK_FAILED`	A hook failed and `errorHandling` is `stop`.
`HOOK_TIMEOUT`	A hook exceeded the 5-minute timeout.
`INTERACTIVE_JSON_CONFLICT`	`--interactive` and `--json` cannot be used together.
`INTERACTIVE_NOT_TTY`	`--interactive` requires a TTY.
`RESOURCE_NOT_FOUND`	The resource ID does not exist.
`RESOURCE_EDIT_FIELD_REQUIRED`	`res edit` was called without any editable field.
`RESOURCE_EDIT_CONTENT_CONFLICT`	`--file` and `--content` cannot be used together.
`RESOURCE_EDIT_TYPE_MISMATCH`	Edit fields do not match the resource type.
`UNSUPPORTED_RESOURCE_TYPE`	The resource type is not `template` or `doc`.
`LOCAL_WORKSPACE_UNSUPPORTED_OPTION`	Options such as `--parent-id` are only supported in Cloud workspaces.
`CONFIRMATION_REQUIRED`	`res remove` is missing `--yes`.
`DOC_CONTENT_REQUIRED`	Neither `--file` nor `--content` was provided when adding a document resource.
`DOC_FILE_READ_FAILED`	The file passed via `--file` is unreadable.
`AUTH_TOKEN_UNAVAILABLE`	Not logged in or no usable token; run `ag login` first.
`API_KEY_REQUIRED`	`--api-key` was given an empty value.
`OAUTH_PORT_UNAVAILABLE`	All 10 OAuth callback ports starting at 51280 are occupied.
`OAUTH_TIMEOUT`	Timed out waiting for the OAuth callback.
`WORKSPACE_NOT_FOUND`	The workspace ID does not exist; after login, run `ag space list --refresh`.
`CONFIG_KEY_REQUIRED`	`config get` is missing the key argument.
`UNEXPECTED_ERROR`	Unexpected error; please report it with the `--json` output attached.

Data Directory and Environment Variables

Default data directory:

~/.agilebuilder/v2

File	Purpose
`config.json`	CLI configuration (see the `config` command).
`current-space.json`	The currently selected workspace ID.
`resources/local.json`	Local template and document resources.
`auth.enc`	Encrypted authentication data.
`license-cache.json`	Cached license and Cloud workspace list.

Environment variable	Description
`AGILEBUILDER_CORE1_DATA_DIR`	Override the data directory; useful for CI isolation and testing.
`AGILEBUILDER_LANG`	Override the CLI output language (takes precedence over `LC_ALL` and friends when `language` is `auto`).

AGILEBUILDER_CORE1_DATA_DIR=/tmp/agilebuilder-core ag res list

MCP Server Mode

The package ships an MCP stdio server exposed as the agilebuilder-mcp command. MCP-capable AI IDEs can call it to query resources, read document context, and scaffold projects. See MCP Integration for configuration and the tool list.

Known Limitations

Only after_write shell hooks are executed today; see File Patterns and Hooks.
Local resources are a flat list with no folders.
Cloud operations depend on the availability of the AgileBuilder backend API and your permissions.