open-phiz-cli

Command-line and CI client for Open Phiz developer APIs. Node.js 22.12 or newer is required.

Configure

Create a short-lived Personal Access Token in the Open Platform Dashboard and expose it through the environment. The CLI deliberately rejects token and secret command-line arguments so credentials do not enter shell history or process listings.

export PHIZ_BASE_URL=https://open.example.com
export PHIZ_TOKEN="$OPEN_PHIZ_CI_TOKEN"

Use dev_scope.miniApp.read and dev_scope.miniAppVersion.read for list and status commands. Package upload additionally requires dev_scope.miniAppCI. Lifecycle writes require dev_scope.miniAppVersion.write. Keep upload and release credentials on separate, short-lived PATs; an upload-only token cannot submit, publish, unpublish, or roll back a version.

Commands

phiz mini-app list
phiz mini-app list --page 2 --page-size 50 --keyword checkout --json
phiz mini-app status --app-id wx_example --json
phiz mini-app upload \
  --app-id wx_example \
  --file ./dist/mini-app.zip \
  --version 1.4.0 \
  --remark "CI draft" \
  --wait \
  --json
phiz mini-app review submit --app-id wx_example --version-id <id> --confirm --wait --json
phiz mini-app review withdraw --app-id wx_example --version-id <id> --confirm --json
phiz mini-app publish --app-id wx_example --version-id <id> --confirm --wait --json
phiz mini-app unpublish --app-id wx_example --version-id <id> --confirm --wait --json
phiz mini-app rollback-list --app-id wx_example --json
phiz mini-app rollback --app-id wx_example --version-id <id> --confirm --wait --json

--json emits one JSON object and uses a non-zero exit code for failures. Errors include a stable code, HTTP status, Request ID when available, and whether the failure is retryable. Response bodies and credentials are never included in diagnostic errors.

Upload accepts a regular .zip file with a ZIP header and a maximum size of 50 MB. The CLI computes SHA-256 before any write, and the server verifies the digest both while receiving the file and before creating the draft from stored content.

The default idempotency key is deterministically derived from app ID, version, and package SHA-256. Upload and build use separate derived keys. A retry after a timeout reuses completed server results; rerunning the same command also recovers a visible draft only when its version and digest both match. The same version with a different or unverifiable digest fails with VERSION_CONFLICT. Use --idempotency-key only when an external CI system needs to supply its own stable recovery key.

Idempotent GET, upload, and build requests are retried at most twice. HTTPS is mandatory outside localhost unless --allow-insecure-http or PHIZ_ALLOW_INSECURE_HTTP=1 is set for an isolated development network. --wait polls draft visibility for up to 120 seconds by default; adjust with --wait-timeout and --poll-interval.

Every lifecycle write requires --confirm, binds the public App ID to the target Version ID, and uses a deterministic idempotency key. The CLI queries version status after the write; --wait keeps polling until the review, draft, online, or offline state is visible. Use rollback-list before a rollback to select a version that was previously published. --auto-publish is accepted only by review submit and publishes after a successful review decision.

GitHub Actions

The official reusable workflow keeps upload and release credentials separate. Pin both the workflow reference and cli_version to immutable released versions. Store an upload-only PAT as OPEN_PHIZ_UPLOAD_TOKEN; add OPEN_PHIZ_RELEASE_TOKEN only when the job submits a review.

jobs:
  open_phiz_release:
    uses: phiz-clip/open-phiz/.github/workflows/[email protected]
    with:
      base_url: ${{ vars.OPEN_PHIZ_BASE_URL }}
      app_id: ${{ vars.OPEN_PHIZ_APP_ID }}
      package_path: dist/mini-app.zip
      version: 1.4.0
      cli_version: 0.1.0
      submit_review: true
      auto_publish: false
    secrets:
      upload_token: ${{ secrets.OPEN_PHIZ_UPLOAD_TOKEN }}
      release_token: ${{ secrets.OPEN_PHIZ_RELEASE_TOKEN }}

The workflow defaults to draft upload only. It exposes version_id as a reusable workflow output and safely recovers a matching draft when a previous run stopped after the server accepted it.

GitLab CI

Include the official hidden job from an immutable tag, extend it in the caller pipeline, and set OPEN_PHIZ_UPLOAD_TOKEN and OPEN_PHIZ_RELEASE_TOKEN as masked, protected variables. Omit the release token when OPEN_PHIZ_SUBMIT_REVIEW remains false.

include:
  - remote: https://raw.githubusercontent.com/phiz-clip/open-phiz/v0.1.0/ci/gitlab/open-phiz-mini-app-release.yml

open_phiz_release:
  extends: .open-phiz-mini-app-release
  variables:
    PHIZ_BASE_URL: https://open.example.com
    OPEN_PHIZ_APP_ID: wx_example
    OPEN_PHIZ_VERSION: 1.4.0
    OPEN_PHIZ_CLI_VERSION: 0.1.0
    OPEN_PHIZ_SUBMIT_REVIEW: 'true'
    OPEN_PHIZ_AUTO_PUBLISH: 'false'