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` 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.

## Core workflow

```bash
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.
- `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
  project-level `push-branch` (defaults to `main`).
- `--debug` on any command prints full request/response logs (tokens masked) — use it when
  diagnosing failures.

## Project plugins and private skills

The CLI exposes only the server allowlist of project plugins:

- `SUPERUN_CLOUD`
- `SUPERUN_AI`
- `SUPERUN_MANAGED_AGENT_V2`
- `SUPERUN_STORAGE`
- `TTS`
- `ASR`
- `VIDEO_GENERATE`
- `NANO_BANANA`
- `OCR`

Use `sxq plugin list` or `sxq plugin status [pluginId]` to inspect them. `sxq plugin enable <pluginId>`
waits for the remote integration lifecycle and, after success, installs its private skills.
`sxq plugin disable <pluginId>` may also disable dependent plugins and requires interactive
confirmation.

Plugin skills are private, plugin-owned resources rather than the general Superun skill catalog.
When an agent needs one, it must run `sxq plugin skill <pluginId>` itself. The command force-upgrades
all files for every associated skill into `.superun/skills/<skillId>/`; a skill may include
`SKILL.md`, references, scripts, assets, and other files. Do not edit those generated files because a
later plugin operation may overwrite them with the newest server version.

`.superun/skills/` is deliberately outside project attachment sync: `sxq pull` never reads,
overwrites, or tracks it, and `sxq push` never uploads it. Plugin capability commands upgrade the
relevant private skills before use.

## Git collaboration safety

`.sxq/attachments.json` is a local synchronization baseline, not a Git index. The `.sxq/`
directory is intentionally ignored by Git, so switching branches changes the working tree without
changing that baseline. A file that is older, different, or absent on the new branch can therefore
look like an intended modification or deletion even when nobody edited or removed it manually.

- Run `sxq pull`, `sxq push`, and `sxq db push` only from the branch intended to sync with Superun.
  Git projects allow all three local-file operations only from the project-level `push-branch`
  (`main` by default). Configure a different branch with `sxq config set push-branch <branch>`.
- Prefer a separate Git worktree for each concurrently used branch. Link and pull each worktree
  separately so every worktree has its own `.sxq` baseline. Never copy `.sxq` between repositories,
  worktrees, branches, or partial source directories, and never force-add it to Git.
- After switching branches in a directory that already contains `.sxq`, do not push immediately.
  Return to the configured push branch, run `sxq pull`, inspect `git status` / `git diff`, and review
  the complete push plan. Treat unexpected bulk modifications or deletions as a stale/mismatched
  working tree and stop instead of confirming.
- `-f` on `pull`, `push`, or `db push` bypasses only branch restrictions; it does not prove that the
  working tree matches the user's intent. Use it only when the user explicitly authorizes operating
  on that exact branch. Do not use it to bypass reset/rebase/history or worktree warnings.
- `sxq push -y` still prints the plan but skips the prompt. Use it only after the exact added,
  modified, and deleted paths have been reviewed and authorized. Never combine `-f -y` as a generic
  retry for a failed push.
- Non-Git directories skip Git-specific checks, but the push plan remains authoritative: stop on
  surprising changes and confirm only the intended files.

## Database migrations (`sxq db push`)

Superun projects use Supabase. Schema changes MUST go through migration files executed by
`sxq db push` — never by pushing SQL files with `sxq push` (the CLI blocks any change under
`supabase/migrations/` during a normal push).

Full flow:

1. Write the DDL in a new file under `supabase/migrations/`. Its name MUST strictly match
   `<yyyyMMddHHmmss>_<identifier>.sql`: the prefix is exactly 14 digits, generated with
   `date +%Y%m%d%H%M%S` (for example,
   `20260506210939_b9c21d2a344c4871b08a744b2e724176.sql`). The timestamp prefix is the replay
   ordering key and MUST be unique across the project's migrations. Before creating a migration,
   inspect the existing filenames; if the timestamp already exists, generate a later one rather
   than reusing it. Do not use Unix timestamps, dates with separators, shortened dates, or any
   other prefix width: lexical filename order would no longer reliably match migration time.
2. Run `sxq db push`. It will:
   - apply the same Git local-file safety checks as `pull` and `push` before reading or writing
     project files (`-f` only ignores configured/manifest branch restrictions);
   - pull remote changes first (aborts if there are merge conflicts — resolve, then rerun);
   - diff local files against the remote baseline to find migrations that are new;
   - abort the entire pending batch before executing any SQL if any new `.sql` filename does not
     contain an exact 14-digit `yyyyMMddHHmmss` prefix;
   - reject the entire pending batch before executing SQL if a new migration reuses a timestamp
     from another pending migration or an existing remote migration;
   - execute the new migrations one at a time, in ascending timestamp order;
   - stop at the first failure and print the server's error message. Migrations before the
     failed one are already applied; fix the failing file and rerun — only the remaining
     (still-new) migrations execute again;
   - after success, the server stores each migration file as a project attachment
     automatically, and the CLI runs a final pull so the local manifest matches.
3. Never edit an already-executed migration file — it is part of the remote baseline; write a
   new migration instead.
4. Migration SQL should be idempotent where possible (`create table if not exists`, `drop ... if exists`).

## Database queries and logs

Every `sxq db` command requires `SUPERUN_CLOUD=ENABLED` and first force-upgrades that plugin's private
skills.

- `sxq db query [sql] [--file <path>] [--limit <n>] [--json]` runs SQL against Debug by default and
  accepts exactly one SQL argument, file, or stdin stream. Debug permits writes for development;
  durable, replayable schema changes should still use a migration plus `sxq db push`.
- `sxq db logs [--type <type>] [--since <range>] [--filter <text>] [--limit <n>] [--json]` queries
  superun Cloud logs. Use `sxq db logs --help` for the supported log types and time ranges.
- Add `--prod` to `db query` or `db logs` only when the linked project has isolated deployment
  enabled. Without `--prod`, isolated projects query Debug and may write. With `--prod`, they query
  Production and both CLI and backend enforce read-only SQL. If isolated deployment is not enabled,
  `--prod` fails instead of silently querying the current database.

## Rules of thumb

1. Run `sxq pull` before editing if the project may have changed remotely (e.g. the user also
   edits on the Superun web UI).
2. After pushing code changes the user wants to see: `sxq preview` for a preview; only run
   `sxq deploy` when they ask to go live, then leave the final confirmation to the user in the browser.
3. `deploy --status` is read-only and always safe for checking state.
4. Exit code 0 means the requested CLI action succeeded. For `sxq deploy`, it only means the
   release confirmation page was opened, not that the project was released. Non-zero exit prints
   an actionable error message on stderr — read it before retrying.
5. Never commit or expose the contents of `.sxq/` (it contains the sessionId and session
   metadata; anyone with the sessionId may be able to read project files).

## Maintainer release SOP

Use this workflow only when the user explicitly asks to publish `suxiaoqiang-cli` itself. An app
release through `sxq deploy` is a different workflow and does not authorize any package, GitHub,
plugin, or documentation publication.

1. Prepare one complete release from a branch that descends from the latest `origin/main`:
   - bump the CLI version in `package.json` and `package-lock.json`;
   - if the skill changed, bump both
     `plugins/suxiaoqiang-cli/.claude-plugin/plugin.json` and
     `plugins/suxiaoqiang-cli/.codex-plugin/plugin.json` to the same plugin version;
   - keep `plugins/suxiaoqiang-cli/skills/suxiaoqiang-cli/SKILL.md` as the canonical skill source;
   - run `npm run build`, `npm pack --dry-run`, and inspect the package file list before publishing.
2. Publish GitHub first, after explicit authorization for the external writes:
   - merge the reviewed release commit to `main`, create and push tag `v<CLI version>`, then create
     the matching GitHub release;
   - verify the remote `main` commit, tag, and release independently;
   - verify the canonical skill is readable from
     `https://raw.githubusercontent.com/AiGuangInc/suxiaoqiang-cli/main/plugins/suxiaoqiang-cli/skills/suxiaoqiang-cli/SKILL.md`.
3. Publish npm only after GitHub succeeds: run `npm publish --access public`, then require
   `npm view suxiaoqiang-cli version` to equal the intended CLI version. Install that exact version
   in an isolated location and exercise the changed CLI behavior; a successful build alone is not
   release acceptance.
4. Publish the user-facing skill/CLI documentation last, using fresh branches from each docs
   repository's latest `origin/main`:
   - main site (`docs.superun.com`): repository `vijayqian-sys/superun`, update
     `superun/cli/suxiaoqiang-cli.mdx` and its `zh-Hant` translation;
   - international site (`docs.superun.ai`): repository `qianwujie0905/documentation`, update
     `superun/cli/suxiaoqiang-cli.mdx` plus its `zh-Hans` and `zh-Hant` translations;
   - merge both documentation changes, then fetch
     `https://docs.superun.com/superun/cli/suxiaoqiang-cli.md` and
     `https://docs.superun.ai/superun/cli/suxiaoqiang-cli.md` and verify the newly changed content
     is live.
5. Stop on the first failed publication or live verification. Report GitHub, npm, main-site docs,
   and international-site docs as separate outcomes; never describe the full release as complete
   while any one of them is missing or stale.