@byteplus-iga-pages/cli 0.0.0-stage → 1.1.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BytePlus Pte. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,291 @@
-# Temporary Holding Version
+<br/>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+  <h3 align="center">BytePlus IGA Pages CLI</h3>
+</div>
+
+<br/>
+
+## 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.
+
+<br/>
+
+## Prerequisites
+
+To get started, create an account with [BytePlus](https://console.byteplus.com).
+
+<br/>
+
+## Installation
+
+```bash
+npm install -g @byteplus-iga-pages/cli
+```
+
+Verify the installation:
+
+```bash
+iga -v
+iga -h
+```
+
+<br/>
+
+## Commands
+
+### `bp-iga login`
+
+Authenticate with your BytePlus account:
+
+```bash
+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`
+
+```bash
+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
+```
+
+Download a template into a new or empty directory. 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 `bp-iga pages dev`.
+
+---
+
+### `bp-iga switch`
+
+Switch to a different BytePlus account by re-running the login flow.
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+bp-iga pages deploy                        # deploy current project
+bp-iga pages deploy --logs                 # stream complete build logs
+```
+
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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`).
+
+```bash
+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
+```
+
+Bind or unbind an existing AI Gateway in a linked project directory:
+
+```bash
+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.
+
+```bash
+bp-iga logout
+```
+
+---
+
+### `bp-iga whoami`
+
+Display information about the currently authenticated account.
+
+```bash
+bp-iga whoami
+```
+
+## License
+
+MIT © BytePlus Pte. Ltd.

package/bin/bp-iga.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+require('../dist/index.js');
+