suxiaoqiang-cli

suxiaoqiang-cli (sxq)

English | 简体中文

sxq is the official command-line tool for Superun, the vibe coding platform. It syncs your Superun project files to your local machine so you can edit them with your favorite editor or AI coding agent, then push changes back, trigger a preview build, and open the production release confirmation page.

Installation

Requires Node.js >= 18.

npm install -g suxiaoqiang-cli

Or run from source:

git clone https://github.com/AiGuangInc/suxiaoqiang-cli.git
cd suxiaoqiang-cli
npm install
npm run build
npm link   # makes the `sxq` command available globally

Quick start

# 1. Log in (opens a browser for authorization)
sxq login

# 2. Link a local directory to your Superun project
mkdir my-app && cd my-app
sxq link <sessionId>        # sessionId is shown in the Superun project URL

# 3. Pull the project files
sxq pull

# 4. Edit locally, then push your changes back
sxq push -m "tweak homepage copy"

# 5. Update the frontend preview and wait for it
sxq preview                 # same as sxq preview front; prints the preview URL when done

# Update only the Edge Function preview when needed
sxq preview ef

# 6. Open the production release confirmation
sxq deploy                  # opens the project release confirmation page in your browser

Commands

Command	Description
sxq login [-y] [--pat / --stdin / --token <token>]	Obtain and save a PAT via browser authorization, or import a credential with hidden input, stdin, or an existing token (validated before saving).
sxq logout	Delete the saved login credential for the current API environment. Does not revoke the PAT on the server or unset SUPERUN_PAT.
sxq link <sessionId> [-y]	Link the current directory to a project. Requires code sync permission, project access, and stage 2 (demo) or later after style selection.
sxq pull [-f]	Pull remote files. Incremental after the first pull, with three-way merge; conflicts get git-style <<<<<<< markers. Git projects only operate on the configured branch by default.
sxq push [-f] [-y] [-m <msg>]	Pull first, show the complete add/modify/delete plan, then push after confirmation. Git projects only push from the configured branch by default; -f ignores branch restrictions and -y skips confirmation.
sxq preview [front|ef]	Update the preview environment; defaults to front, while ef deploys Edge Functions only.
sxq publish	Compatibility alias for sxq preview front.
sxq deploy	Open the linked project's release confirmation page. The CLI does not release directly.
sxq deploy --status	Show pending / published versions and the live URL without releasing.
sxq plugin list|status|enable|skill|disable	Manage allowlisted project plugins; skill force-installs/upgrades private plugin skills.
sxq db push [-f] [-m <msg>]	Execute new database migrations under supabase/migrations/; Git projects only operate on the configured branch by default.
sxq db query [sql] [--file <path>] [--prod] [--limit <n>] [--json]	Run SQL; Debug permits writes, while --prod queries the isolated live database read-only.
sxq db logs [--type <type>] [--since <range>] [--prod] [--json]	Query superun Cloud logs; use --prod for live logs when isolated deployment is enabled.
sxq config set|get|unset|list	Manage config. Keys: host, lang (zh / en), and project-level push-branch (default main).
sxq upgrade	Upgrade the CLI to the latest version from npm.

Mandatory upgrade policy

The CLI refreshes npm dist-tags on the first command each day; later commands that day only read the local cache. latest only produces the normal update notice, while the maintainer-controlled required tag is the minimum allowed version. When the installed version is below required, the CLI upgrades itself to the latest version through npm and then re-runs the original command with the new CLI. sxq upgrade, sxq logout, --version, and --help always run directly.

Only enable or raise the minimum after the target version has been published and verified:

npm dist-tag add suxiaoqiang-cli@<minimum-version> required
npm dist-tag rm suxiaoqiang-cli required  # disable mandatory upgrades

If the npm registry is temporarily unavailable, the CLI keeps enforcing the last successfully read policy. A machine with no cached policy fails open so a registry outage cannot disable every command.

The gate can only govern CLI versions that already contain this capability. Roll out the first capable release as a normal update before using required; a dist-tag cannot retroactively change clients published before the gate existed.

Project plugins and private skills

The CLI only exposes project plugins on the server-managed allowlist. The first version supports SUPERUN_CLOUD, SUPERUN_AI, SUPERUN_MANAGED_AGENT_V2, SUPERUN_STORAGE, TTS, ASR, VIDEO_GENERATE, NANO_BANANA, and OCR.

sxq plugin list
sxq plugin enable SUPERUN_CLOUD
sxq plugin skill SUPERUN_CLOUD

sxq plugin skill force-upgrades every private skill file associated with the plugin and writes it under .superun/skills/<skill-id>/. A skill can contain SKILL.md, references, scripts, and other files. Agents should install a plugin skill themselves with sxq plugin skill <PLUGIN_ID> when needed.

.superun/skills/ is outside project code synchronization: sxq pull never reads or overwrites it, and sxq push never uploads it. Plugin capability commands force-upgrade their relevant private skills before running; every sxq db operation upgrades the SUPERUN_CLOUD skills.

Claude Code and Codex plugins

This repository publishes one shared suxiaoqiang-cli skill for both Claude Code and Codex. The plugin teaches the agent how to drive sxq safely; the CLI itself must still be installed from npm.

Claude Code

Install:

claude plugin marketplace add AiGuangInc/suxiaoqiang-cli
claude plugin install suxiaoqiang-cli@suxiaoqiang

Update to the latest skill and restart Claude Code:

claude plugin marketplace update suxiaoqiang
claude plugin update suxiaoqiang-cli@suxiaoqiang

Codex

Install:

codex plugin marketplace add AiGuangInc/suxiaoqiang-cli --ref main
codex plugin add suxiaoqiang-cli@suxiaoqiang

Refresh the marketplace, reinstall the latest plugin version, and start a new task:

codex plugin marketplace upgrade suxiaoqiang
codex plugin add suxiaoqiang-cli@suxiaoqiang

Database migrations

Create each migration under supabase/migrations/ using the strict <yyyyMMddHHmmss>_<identifier>.sql format. The prefix must contain exactly 14 digits, for example 20260506210939_b9c21d2a344c4871b08a744b2e724176.sql. It determines replay order and must be unique across the project. If any new SQL file does not match this format, sxq db push aborts the entire batch before executing SQL. Then run:

sxq db push -m "add user profile tables"

It pulls first and finds migrations that don't exist remotely yet. If a pending migration reuses a timestamp from either another pending migration or an existing remote migration, it aborts before executing any SQL; otherwise it executes migrations one by one in timestamp order, stopping at the first failure and printing the error. The server stores each successful migration as a project attachment automatically, so don't push migration files with sxq push (the CLI blocks them).

SQL and log queries:

sxq db query "select * from users limit 20"
sxq db query --file query.sql --json
sxq db logs --type function --since 15m

With isolated deployment enabled, these commands query Debug by default and query Production only with --prod. --prod fails explicitly when isolated deployment is not enabled. Debug queries may write for development workflows; --prod is enforced read-only by both the CLI and backend. Use migration files and sxq db push for durable, replayable schema changes.

Notes

• .gitignore support: pull / push respect your project's .gitignore (plus built-in ignores like node_modules, dist, .git). Ignored files are never synced.
• Plugin skill isolation: .superun/skills/ is managed only by sxq plugin skill and plugin capability commands; it never enters the pull / push attachment manifest.
• Git local-file guard: pull, push, and db push only operate on the configured push-branch and reject merge/rebase intermediate states, mismatched worktrees, or rewritten history. Non-Git projects skip these checks. Use sxq config set push-branch master to change the project branch; -f only ignores branch restrictions.
• Push plan confirmation: push lists every added, modified, and deleted file and asks for y/N confirmation by default. -y means the list has been reviewed and accepted.
• Non-interactive / CI / AI agents: terminal confirmation prompts have a -y flag and fail fast outside a TTY. Production release confirmation always happens in the browser; sxq deploy cannot bypass it.
• Language: auto-detected from your locale; override with sxq config set lang en.
• Production releases: sxq deploy only opens the release confirmation page. Review and confirm the release in the browser.

License

Apache-2.0

PAT authentication

Run sxq login to authorize in the browser. The CLI exchanges the temporary token through PersonalAccessToken/create and saves the resulting sup_pat_ PAT in the system credential store: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Login credentials are separated by API base URL; changing host does not reuse another environment's saved token.

The CLI uses the system credential store by default. On headless Linux without a session D-Bus, it selects a local plaintext file with a warning (Unix mode 0600). A locked, inaccessible, or broken system store stops the command instead of silently switching to plaintext. Credentials are read, saved, and deleted only in the selected store. An empty system store does not cause a fallback to local credentials. If no credential exists, log in again. When the system store is usable, the current host’s local plaintext token and the old-version login token field are deleted, even if the system store is empty. Credentials are never migrated between stores. Changing the API host does not move credentials.

Headless environments may inject SUPERUN_PAT from a secret manager without using either store. Linux system storage requires Secret Service and session D-Bus; native platform packages require npm optional dependencies. An unlocked, authorized system store generally does not prompt on every command, but OS policy, locking, or Node upgrades may cause another prompt. Neither plaintext files nor the system store fully isolate credentials from malicious software running as your account.

• sxq login --pat: enter an existing PAT with hidden input; validate it before saving.
• sxq login --stdin: read a PAT from standard input for password managers or scripts; failed validation preserves the previous credential.
• SUPERUN_PAT: the same environment variable as superun-ai; overrides the saved credential for all API requests via the access-token header. With it set, sxq login validates the environment credential without saving it or opening a browser. Empty or malformed values fail explicitly.