/suxiaoqiang-cli

name: suxiaoqiang-cli
description: >
  Use suxiaoqiang-cli (sxq) to sync, edit, preview, release, manage allowlisted project plugins,
  install private plugin skills, and query Superun Cloud databases or logs from the terminal.
  Use when the user mentions sxq, suxiaoqiang-cli, a Superun sessionId, project plugin management,
  db query/logs/migrations, or explicitly requests a maintainer release of the CLI, npm package,
  plugin skill, or documentation. 当用户提到 sxq、suxiaoqiang-cli、Superun sessionId、项目插件、
  私有插件技能、数据库查询/日志/迁移，或明确要求发布 CLI、npm 包、插件 skill 或文档时使用。

suxiaoqiang-cli (sxq)

`sxq` syncs a Superun project (identified by a `sessionId`) with a local directory, drives the preview pipeline, and opens the browser for production release confirmation. In Claude Code and Codex environments, use non-interactive flags only after the user has authorized the exact operation. In particular, never add `-y` to `sxq push` before reviewing its add/modify/delete plan.

Prerequisites

• `sxq login` obtains a `sup_pat_` PAT after browser authorization. `SUPERUN_PAT` overrides the

saved credential for all API calls; with it set, login only validates it without opening a browser or saving it. Empty or malformed environment values fail explicitly. Manual PAT import supports hidden input (`sxq login --pat`) and stdin (`sxq login --stdin`), with online validation before saving. Existing `--token` credentials remain supported. Business PATs are separate from the domestic pre-release gateway `PRIVATE_TOKEN`.

• Login credentials use the system credential store by default. On headless Linux without session

D-Bus, they use a local plaintext file (Unix mode 0600) with a warning; locked or failing system stores stop the command instead of silently downgrading. Only the selected store is read or written, scoped by API base URL. An empty system store does not trigger file fallback. There is no credential migration or old-token import: if no credential is present, the user logs in again. Selecting a usable system store deletes the current host’s plaintext login token and the old login token field, even when the system store is empty. `SUPERUN_PAT` bypasses both stores. Linux system storage requires Secret Service and session D-Bus; native bindings require npm optional dependencies. `sxq logout` clears only the selected store for the current host (including plaintext cleanup when the system store is usable), not the server PAT or environment variable. It bypasses upgrade gates.

• Browser-based `sxq login` requires a browser and must be done by the user. If any command reports

"Not logged in / 未登录" or "credential expired / 凭证无效", ask the user to run `sxq login` themselves — do not attempt it. Exception: if the user hands you a token, run `sxq login --token <token>` (it validates the token and keeps the previous credential on failure). Never ask the user to paste a token proactively.

• A project directory is bound via `.sxq/config.json` (created by `sxq link`). Check for it

before assuming a directory is linked.

• `sxq link` requires stage 2 (demo) or later. Complete style selection in Superun first;

a missing, invalid, or earlier stage is rejected before changing the local binding.

Core workflow

sxq link <sessionId> -y     # bind current dir to a project (verifies ownership; needs login)
sxq pull                    # pull remote files (incremental, three-way merge)
# ... edit files locally ...
sxq push -m "<summary>"     # review add/modify/delete plan, then confirm the push
sxq preview                 # update the frontend preview; equivalent to sxq preview front
sxq preview ef              # update only the Edge Function preview
sxq deploy                   # open the linked project's release confirmation page
sxq deploy --status         # read-only: pending/published versions + live URL

Command details & flags

• `sxq push [-f] [-y] [-m <message>]` — pulls first, then lists every added, modified, and deleted

text file before pushing. Git projects default to the project-level `push-branch` (`main`); `-f` ignores branch restrictions, while `-y` confirms the displayed plan without an interactive prompt. Only use `-y` after the user has authorized the exact push. Respects `.gitignore` plus built-in ignores (`node_modules`, `dist`, `.git`; binaries and files over 5MB are skipped). If it aborts with conflict markers (`<<<<<<< local`), resolve the listed files, then push again. Large aggregate requests automatically upload text in batches, then commit rowKey references with the original snapshot guard. Small pushes retain direct submission. Failed uploads do not commit project files; a single file whose JSON encoding exceeds the upload limit is rejected before upload.

• `sxq preview [front|ef] [--message-id <id>]` — updates the preview environment. `front` is

the default and polls the preview build for up to 10 min; `ef` deploys all Edge Functions from the linked project's latest completed mainline version. `--message-id` only applies to `front`. The legacy `sxq publish` command remains available for compatibility, prints a deprecation warning, and then runs the same behavior as `sxq preview front`.

• `sxq deploy` — opens the linked project's release confirmation page in the user's browser.

It never calls the release API directly. The user must review and confirm the release on the page; agents must not claim that a release happened just because this command exited 0.

• `sxq pull [-f]` — local-only edits are preserved via three-way merge. Git projects only operate

on the configured `push-branch` by default and apply the shared local-file safety checks before writing the worktree. Conflicted files are listed and contain git-style markers; resolve before pushing. `-f` only ignores configured/manifest branch restrictions.

• `sxq config set|get|unset|list` — keys: `host` (API base URL), `lang` (`zh`/`en`), and the

pr