Pages and Agent project compatibility

Use bp-iga pages for Pages projects and iga agents for new Agent projects. Existing Pages projects can continue using the Agent and Blob SDKs with bp-iga pages dev/deploy; no migration is required.

The CLI uses .iga/project.json to identify the associated project: appType: "agent" selects Agent, and a missing appType selects Pages. Using the other command group reports an error and points to the original project's commands. link changes the local association to another project; it does not migrate the remote project.

A directory without projectId is only unlinked. After a fresh checkout, use bp-iga pages link --project <id-or-name> to restore an existing Pages association, including projects using Agent or Blob SDKs. Creating a new Pages project with these SDKs is blocked; use iga agents for new projects instead.

When pages init selects a template tagged as agent, it stops before downloading and directs you to iga agents init --list --json. Select a template ID from that list to initialize an Agent project.

Agent AI Gateway integrations

iga agents integration list/link/unlink manages AI Gateway bindings for an Agent project. Agent integrations only support aigateway; Supabase integration remains available under pages.

iga agents integration list --format=json
iga agents integration link aigateway --resource <gateway-id>
iga agents integration unlink aigateway --resource <gateway-id> --yes
iga agents env pull

Omitting the integration name selects aigateway. Region, branch and prefix options are not supported. Binding changes apply on the next deployment; env pull refreshes local configuration.

Overview

BytePlus IGA Pages is a full-stack development and deployment platform powered by BytePlus IGA. It supports static sites, server-side rendering, and serverless functions, delivering projects to a global edge network with zero infrastructure management.

@byteplus-iga-pages/cli is the official command-line interface for BytePlus IGA Pages, helping you manage projects, develop locally, and debug Functions from your terminal.

Prerequisites

To get started, create an account with BytePlus.

Installation

npm install -g @byteplus-iga-pages/cli

Verify the installation:

iga -v
iga -h

Commands

bp-iga login

Authenticate with your BytePlus account:

bp-iga login                                   # local browser login
bp-iga login --remote                          # cross-device login (e.g. SSH)
bp-iga login --accessKey <AK> --secretKey <SK>  # AK/SK for automation

--remote cannot be combined with AK/SK.

bp-iga pages init / iga agents init

bp-iga pages init --list --json
bp-iga pages init my-agent --template <template-id>
bp-iga pages init my-agent --template <template-id> --name my-remote-project

Use iga agents init my-agent --template <template-id> --sandbox to create and link a remote Agent with Sandbox enabled, including templates without model configuration. --sandbox is Agent-only and cannot be combined with --list. Without this flag, Agent initialization follows the template’s ProjectParam.Context.Sandbox.Enable setting; missing configuration uses the backend default (disabled). Templates without model configuration do not create an AI Gateway.

Download a template into a new or empty directory. Use iga agents init for Agent projects and templates that directly depend on the Agent or Blob SDK. AI templates also create a remote project, bind an AI Gateway, and write .env.local. Use --name to override the directory-based project name. Install dependencies, then run iga agents dev or bp-iga pages dev for the corresponding project type.

bp-iga switch

Switch to a different BytePlus account by re-running the login flow.

bp-iga switch

bp-iga logout removes only the local ~/.bp-iga/auth.json; it does not revoke the server-side Refresh Token.

bp-iga pages link

Link the current directory to an BytePlus IGA Pages project. The CLI auto-detects a matching project by directory name, or lets you pick from your existing projects. If no project exists yet, it can create one (including GitHub-connected projects when a Git remote is detected).

bp-iga pages link
bp-iga pages link --format=json
bp-iga pages link --yes --format=json
bp-iga pages link --project <project-id-or-name> --yes

--format=json controls the output format. Without an execution option, it prints existing project choices, the directory-derived default project name, a matching project when one exists, and a suggested nextCommand without changing local or remote state. Combined with --yes, --project, or --name, it performs the requested link or creation and prints a status=success result.

--project links to an existing project without prompting. It matches ProjectID first, then ProjectName. If a name is ambiguous, pass the ProjectID from bp-iga pages link --format=json.

bp-iga pages deploy

Build and deploy the current project to the BytePlus IGA Pages edge network. The CLI supports two deployment modes:

• Git-based — If a GitHub remote is detected and authorized, the platform pulls source code directly from the repository.
• Direct upload — Source files are zipped and uploaded when no Git provider is available.

For linked projects (see bp-iga pages link), re-deployment is triggered automatically. For new projects, the CLI walks you through creation first.

bp-iga pages deploy                        # deploy current project
bp-iga pages deploy --logs                 # stream complete build logs

Agent projects support iga agents deploy --sandbox. For a new Agent, Sandbox is enabled during creation. For an existing Agent, the CLI enables Sandbox and waits for the configuration to become ready before deploying. Omitting --sandbox preserves the existing Sandbox configuration. Pages deployments do not accept this flag.

By default, show deployment progress and full logs on failure. Use --logs to stream all build logs.

bp-iga pages inspect

Inspect a deployment from any directory, optionally wait for completion or show its build logs.

bp-iga pages inspect <deployment-id>
bp-iga pages inspect <deployment-id> --wait --timeout 3m
bp-iga pages inspect <deployment-id> --logs
bp-iga pages inspect <deployment-id> --logs --wait --format json

--format json writes only the final summary or three-stage build-log array to stdout. Diagnostics use stderr. --project validates ownership but is not required to resolve the deployment. The summary keeps the API status unchanged, omits provider, and resolves an accessible Preview URL through GetPreviewDomain; preview lookup failure is reported as - or previewUrl: null without failing the command.

bp-iga pages preview

Resolve the preview URL for a project or a specific deployment.

bp-iga pages preview --project <name-or-id>
bp-iga pages preview --project <name-or-id> --deployment <deployment-id>
bp-iga pages preview --json

Without --deployment, the request sends only ProjectID to GetPreviewDomain; no deployment is selected automatically. Without a project argument, the linked project in .iga/project.json is used. JSON output contains previewUrl, projectId, and projectName; deployId is included only when specified.

bp-iga pages logs

Query historical runtime logs for the linked project or an explicit deployment. The default range is the latest 24 hours and the default total limit is 100.

bp-iga pages logs
bp-iga pages logs <deployment-id> --since 1h --limit 250
bp-iga pages logs --project <name-or-id> --content timeout
bp-iga pages logs --content error --level error
bp-iga pages logs --json | jq .

--content and --level generate quoted query clauses. When both are present, the CLI joins them with AND.

Human-readable output removes terminal control sequences from every backend field and renders embedded line controls as visible escapes, so one record stays on one terminal line. Ordinary text is unchanged.

--json/-j emits one stable JSON object per line. Pagination uses the API Context internally; field values remain unchanged and are escaped by JSON encoding. This command is a historical query and does not implement real-time follow.

bp-iga pages dev

Start a local development server. The CLI reads the dev or start script from your package.json, injects the port automatically if the framework supports it, and falls back to framework defaults when no script is found.

bp-iga pages dev                # start on http://localhost:3000

bp-iga pages list

List recent deployments for the currently-linked project, or all projects in your account. Aliased as bp-iga pages ls.

When run inside a linked directory (or with a project name/ID), it lists that project's recent deployments. Otherwise it lists every project in your account, so you can discover a name or ID to link or inspect.

bp-iga pages list                  # linked project's deployments, or all projects
bp-iga pages list my-project       # a specific project's deployments (by name or ID)
bp-iga pages ls --json             # machine-readable output

| Flag | Description | | ---------------- | ------------------------------------------------------------------ | | [project] | Project name or ID (defaults to the linked .iga/project.json) | | --project <id> | Project name or ID (alias for the positional argument) | | --json | Output machine-readable JSON |

bp-iga pages env

Manage project-level environment variables for the linked BytePlus IGA Pages project.

bp-iga pages env list
bp-iga pages env list --format=json
bp-iga pages env add <name> --value <value> --yes
bp-iga pages env update <name> --value <value> --yes
bp-iga pages env remove <name> --yes
bp-iga pages env pull

env list only shows variable names. --format=json returns env[].key and never prints values.

bp-iga pages integration

Manage project integrations: supabase (byteplus_supabase) and aigateway (ai_gateway).

bp-iga pages integration list
bp-iga pages integration list --format=json

bp-iga pages integration link supabase
bp-iga pages integration link supabase --region <region> --format=json
bp-iga pages integration link supabase \
  --product byteplus_supabase \
  --region <region> \
  --resource <workspace-name-or-id> \
  --branch <branch-name-or-id> \
  --framework-prefix NEXT_PUBLIC_ \
  --prefix APP_ \
  --yes

bp-iga pages integration unlink
bp-iga pages integration unlink supabase --format=json
bp-iga pages integration unlink supabase \
  --product byteplus_supabase \
  --resource <workspace-name-or-id> \
  --branch <branch-name-or-id> \
  --yes

Manage AI Gateway integrations:

bp-iga pages integration create aigateway # Create or reuse the shared gateway
bp-iga pages integration link aigateway
bp-iga pages integration link aigateway --resource <gateway-name-or-id>
bp-iga pages integration link aigateway --format=json
bp-iga pages integration unlink aigateway --yes
bp-iga pages env pull

Each project can bind one gateway by name or ID. Unlink it before switching; the instance is kept. Changes take effect on the next deployment. Gateway variables stay server-side and ignore prefixes.

--format=json returns structured choices and next steps for IDEs and agents.

Prefixes must be 1–63 characters, start with a letter, and contain only letters, numbers, or underscores. Use an empty --framework-prefix to skip browser-exposed variables.

bp-iga logout

Sign out of the currently logged-in BytePlus account.

bp-iga logout

bp-iga whoami

Display information about the currently authenticated account.

bp-iga whoami

License

MIT © BytePlus Pte. Ltd.

Agent creation without deployment supports iga agents link --name my-agent --sandbox --yes. This enables Sandbox during creation for both Git and upload projects. --sandbox requires --name, cannot be combined with --project, and is not available under pages link.