websimio-cli

Initialize a new WebSIM app scaffold (repos for ui, api, admin, admin-api, infra, and optional mobile).

Install

npm install -g @websim.io/websimio-cli
websimio --version

Prereqs (private templates)

This CLI is public, but the templates are private to the hudlix org. You must:

gh auth login          # log in to GitHub
gh auth setup-git      # or use SSH with an org-authorized key
# You must be a member of the GitHub org: hudlix (SSO authorized if your org uses SAML)

If you’re not in the org, cloning templates will fail. That’s by design.

Quick start

Create a single component (API only):

websimio init app vmb   --components api   --clone   --provider github --org hudlix --push

Create multiple components:

websimio init app vmb \
  --components ui \
  --components infra \
  --components adminApi \
  --clone --provider github --org hudlix --push

Create All Core components:

websimio init app vmb \
  --clone --provider github --org hudlix --push

Full stack + mobile:

# easiest: add --with mobile
websimio init app vmb \
  --with mobile \
  --clone --provider github --org hudlix --push

All components explicitly (including mobile):

websimio init app vmb \
  --components ui \
  --components api \
  --components admin \
  --components adminApi \
  --components infra \
  --components mobile \
  --clone --provider github --org hudlix --push

Result (example):

vmb-api/
vmb-ui/
vmb-infra/
# (+ vmb-mobile/ if you used --with mobile)

Each folder is a fresh git repo re-initialized on your branch (default main). If --provider github --org hudlix --push is provided, the command creates/pushes remotes in hudlix/*.

Command

websimio init app <slug>

Clone selected components from template repos into independent git repos.

Common flags

• --components <ui|api|admin|adminApi|infra|mobile> (repeatable) – select what to scaffold.
  If omitted, defaults to ui,api,admin,adminApi,infra. Use --with mobile or include mobile explicitly.
• --clone – use git clone (required for private repos). Use this.
• --dir <path> – target directory (default: CWD).
• --branch <name> – local branch for initial commit (default: main).
• --provider <github|gitlab|bitbucket> --org <org> --push – create remotes and push.
• --requireOrg <org> – require GitHub org membership before cloning (default: hudlix).

Template override flags (optional; otherwise read from websim.config.json or ~/.websim/config.json)

• --templateUi <repo#ref>
• --templateApi <repo#ref>
• --templateAdmin <repo#ref>
• --templateAdminApi <repo#ref>
• --templateInfra <repo#ref>
• --templateMobile <repo#ref>

Examples:

# single component
websimio init app myapp --components api --clone

# full stack, create+push GitHub repos under hudlix
websimio init app myapp --with mobile --clone --provider github --org hudlix --push

Config (optional)

Place a websim.config.json in the CWD or ~/.websim/config.json:

{
  "templates": {
    "ui": "hudlix/websim-ui-template#main",
    "api": "hudlix/websim-api-template#main",
    "admin": "hudlix/websim-admin-template#main",
    "adminApi": "hudlix/websim-admin-api-template#main",
    "infra": "hudlix/websim-infra-template#main",
    "mobile": "hudlix/websim-mobile-template#main"
  }
}

You can still override any template via flags.

New Features

North-star structure (resource → action):

Keep topics by resource, then subcommands by verb. Add aliases so today’s init app still works.

websimio app init <slug>           # alias: init app <slug>
websimio app deploy <slug>         # deploy ui/api/... for an env/provider
websimio app status <slug>         # show remotes, branches, CI, envs
websimio app open <slug>           # open dashboards (GitHub/Vercel/etc.)
websimio app destroy <slug>        # tear down remotes & env (guarded)
websimio app add component <slug>  # add ui/api/admin/... later
websimio app rm component <slug>   # remove a component (local & remote)
websimio app add plugin <slug>     # apply a recipe (auth, db, stripe, ...)
websimio app rm plugin <slug>      # rollback a recipe
websimio app list                  # list apps in a workspace

Supporting topics:

websimio component deploy <path>   # low-level; works inside one repo
websimio plugin catalog            # list supported plugins/recipes
websimio env set/get/list          # logical envs: dev/stg/prod
websimio secret set/pull/push      # Doppler/GitHub Actions/Vercel secrets
websimio template list/add/pin     # manage template sources
websimio auth check                # assert gh login + org membership
websimio ci scaffold               # add GH Actions for release/publish/deploy
websimio doctor                    # checks: gh, ssh, node, tools
websimio config set/get            # global defaults (~/.websim/config.json)

Command

Deploy

websimio app deploy <slug> \
  --component ui|api|admin|adminApi|infra|mobile \
  --env dev|stg|prod \
  --provider vercel|railway|fly|aws|gcp|azure \
  [--region <code>] [--no-build] [--push] [--dry-run] [--yes]

Behavior

Resolves - repo (local or remote).

Builds (unless --no-build), configures the provider, deploys. Writes back a deployment record to .websimio.json in that repo (idempotent). If --push, commits any generated infra files and pushes.

Defaults

ui/admin → vercel api/adminApi → railway (or fly) infra → runs infra pipelines (Terraform/CDK) if present.

Add plugin (recipes)

websimio app add plugin <slug> \
  --component ui|api|... \
  --name auth|db|stripe|sentry|emails|queue|search|featureflags|storage \
  [--provider clerk|authjs|fusionauth|okta|...]
  [--yes] [--dry-run]

Behavior (idempotent recipes)

Installs packages, adds env keys, drops starter code, wires imports. Updates a plugins section in /.websimio.json. Supports rollback: websimio app rm plugin ... to reverse the changes. Initial plugin matrix (suggested)

auth → clerk | authjs | fusionauth

db → prisma + postgres (Railway/Fly/AWS RDS)

stripe → server + webhook + UI checkout

sentry → SDK wiring for ui/api

emails → resend | postmark (api + templates)

queue → bullmq + redis (api)

search → meilisearch | elastic (api)

featureflags → unleash | growthbook

storage → s3 | r2 (api + signed URLs for ui)

CLI UX examples

export VERCEL_TOKEN=***
websimio app deploy <slug> --component ui --env dev --provider vercel --dir <workspace-root>

# add auth to UI using Clerk
websimio app add plugin vmb --component ui --name auth --provider clerk

# wire Sentry on API
websimio app add plugin vmb --component api --name sentry

# remove a plugin
websimio app rm plugin vmb --component api --name sentry

# add another component later
websimio app add component vmb --components adminApi --clone --push

# quick health & access checks
websimio doctor
websimio auth check --requireOrg hudlix

Repo layout under src/commands/ (Oclif v4)

src/commands/
  app/
    init.ts              # existing (move from init/app.ts & keep alias)
    deploy.ts
    status.ts
    open.ts
    destroy.ts
    add/
      component.ts
      plugin.ts
    rm/
      component.ts
      plugin.ts
    list.ts
  component/
    deploy.ts            # optional low-level
  plugin/
    catalog.ts
  env/
    set.ts
    get.ts
    list.ts
  secret/
    set.ts
    pull.ts
    push.ts
  template/
    list.ts
    add.ts
    pin.ts
  auth/
    check.ts
  ci/
    scaffold.ts
  doctor.ts
  config/
    set.ts
    get.ts

Troubleshooting

• “Access denied. … not a member of ‘hudlix’.”
  You’re not in the GitHub org or your token/key isn’t SSO-authorized. Get added and/or authorize your token/key for the org.

• COULD_NOT_DOWNLOAD (degit)
  Private repos aren’t accessible via degit. Use --clone.

• Permission denied (publickey)
  Add your SSH key to GitHub and authorize it for the org, or use HTTPS with gh auth setup-git.

• Wrong author or account on commits/push
  Set your git identity and ensure your push credentials match the intended GitHub user:

  git config --global user.name "Your Name"
  git config --global user.email "[email protected]"
  gh auth status

License

MIT