Supe.js ⚡

Supe.js is a CLI toolkit for scaffold planning, policy checks, design guidance, and starter catalog exploration.

⚡ Get Started

Option 1: Persistent Installation (Recommended)

Install once and use supe everywhere system-wide:

npm install -g @supejs/supe

Then use the tool directly from any directory:

# Create a new project
supe init my-app --yes

# Or browse starter presets first
supe preset --list
supe init my-app --framework next

# Check your environment
supe doctor

To upgrade:

npm update -g @supejs/supe

Option 2: One-time Usage (no install needed)

Run directly without installing — equivalent to uvx for Python tools:

npx @supejs/supe init my-app --yes

Benefits of persistent installation:

• Tool stays installed and available in PATH
• No need to download on every use
• Better tool management with npm list -g, npm update -g @supejs/supe, npm uninstall -g @supejs/supe
• Cleaner shell configuration

Shell installer (curl / PowerShell)

Alternative installation via the hosted shell scripts:

# Quick (Unix/macOS) — install from npm via shell script
curl -fsSL https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.sh | sh

# or using wget
wget -qO- https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.sh | sh

Safer (Unix/macOS): download, verify checksum, inspect, then run:

curl -fsSL -o supe-install.sh https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.sh
curl -fsSL -o supe-install.sh.sha256 https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.sh.sha256
# verify (Linux)
sha256sum -c supe-install.sh.sha256
# verify (macOS)
shasum -a 256 -c supe-install.sh.sha256 || true
sh supe-install.sh

Windows (PowerShell) — download, verify, inspect, then run:

# Download installer and checksum
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.ps1" -OutFile supe-install.ps1
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/gwon-omega/supe.js/main/scripts/supe-install.ps1.sha256" -OutFile supe-install.ps1.sha256

# Verify SHA256 of the downloaded script
Get-FileHash -Algorithm SHA256 .\supe-install.ps1
Get-Content .\supe-install.ps1.sha256

# If you trust the file after inspection, run it:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\supe-install.ps1

Note: The installer prefers npm install -g @supejs/supe (published registry package). If not yet published, it falls back to npm install -g . when run from a repository clone. Never pipe blindly from the internet in production — always verify checksums first.

Install from source

git clone https://github.com/gwon-omega/supe.js.git
# or SSH
git clone [email protected]:gwon-omega/supe.js.git
# or GitHub CLI
gh repo clone gwon-omega/supe.js

cd supe.js
npm install
npm install -g @supejs/supe

For local development, link the package globally so supe becomes available system-wide:

npm link
# or, from the repo root on Unix/macOS
./scripts/supe.sh
# on Windows (PowerShell)
.\scripts\supe.ps1

create-super-app command notes

• create-super-app and create-supe-app are binaries exposed by this package (@supejs/supe) after global install.
• Reliable options:
  • npm install -g @supejs/supe then run create-super-app my-app
  • npx @supejs/supe init my-app
• npx create-super-app can 404 unless a separate create-super-app package is published.

CLI

node bin/supe.js

Core commands

supe demo
supe doctor [--json]
supe install-hints [--json]
supe profile --user <id> [--base-dir <path>] [--json]
supe sync --user <id> [--provider <github|gitlab|bitbucket>] [--remote <name>] [--json]
supe policy-check --file <policy.json> [--framework <name>] [--package-manager <pm>] [--ui <lib...>] [--json]
supe design [--theme <neon_noir|calm_pro|sunrise_flow>] [--json]
supe catalog [--json]
supe preset [--list] [--name <preset-id>] [project-name] [--json]
supe starter <project-name> [--framework <name>] [--package-manager <pm>] [--ui <lib...>] [--json]
supe init [project-name] [--framework <id>] [--ui <id>] [--template <id>] [--addons <csv>] [--pm <id>] [--yes] [--no-install]
supe shell

Recommended flow (dev friendly)

supe
supe preset --list
supe starter my-app --framework react --ui tailwind
supe init my-app --yes

Starter templates (presets)

Use supe preset --list to inspect available starter templates. Current template IDs:

• react-fast
• next-enterprise
• edge-vinext
• astro-content
• next-admin-dashboard
• next-ecommerce
• astro-blog
• remix-saas

Generate one with:

node bin/supe.js preset my-app --name next-admin-dashboard --json

Publishing

This package is published as @supejs/supe.

To publish under the scoped name and make it publicly installable:

# ensure you're logged in to npm with the publishing account
npm login
# publish as public scoped package
npm publish --access=public

Users can then install system-wide via npm:

npm install -g @supejs/supe

Or scaffold after installation:

supe init my-app

If you are logged into a different npm account, switch or re-authenticate before publishing:

npm whoami
npm login

Repository ownership

This repository is maintained by @gwon-omega.

Development checks

npm test
node --test tests/*.test.js
node bin/supe.js --help