Developers/CLI Reference/CLI (App Runner)

CLI (App Runner)

The supero command line tool that sets up and runs a generated Supero app on your machine — not a general-purpose account/management CLI.

What the CLI Is

⚠️ Two different programs are called supero

Worth settling before you follow any command on this page. The supero on this page is the app runner you install with pip, and it runs a generated application on your machine. There is a second, unrelated supero installed by the on-premise package, which operates a self-hosted Supero platform — that one is run with sudo and has commands like install-deps, init and start. They share a name and nothing else. If a command here is not recognised, check which of the two you have on your PATH. See On-Premise Deployment for the other one.

The supero package installed via pip is an app runner, not a management CLI. It ships alongside every app you generate (or scaffold by hand) and does exactly one job: take a project directory that has schemas.py, config.py and setup.py, make sure the local environment is configured, register/sync the app with the platform, and start (or containerize) the local server. There is no supero login, supero domains, supero schemas, or supero keys — domain/project registration and schema uploads happen through setup.py, which the CLI invokes for you.

A generated app also ships a run.sh wrapper in its root. run.sh creates a local .venv, installs supero from PyPI into it, and execs python3 -m supero.cli with whatever flags you passed — so ./run.sh and a directly-installed supero command take the same arguments and do the same thing.

ℹ️ Install

pip install supero (Python 3.8+). Installing the package registers the supero console command; the same entry point is also reachable as python3 -m supero.cli.

Quick Start

From the root of a generated app (the directory containing schemas.py, config.py and setup.py):

bash

# Recommended: use the bundled wrapper — it creates .venv and installs supero for you
./run.sh

# Equivalent, once supero is installed in your active environment/venv
pip install supero
supero

A first run walks through project validation, environment/credential setup, platform registration and schema upload, CRUD smoke tests, and then starts the local dev server. Subsequent runs reuse the saved .env and are much faster — they mainly re-sync schemas and re-check the config.

💡 Non-interactive runs

Add --no-interactive to use whatever is already in .env without prompting — useful in CI or scripted rebuilds. The .env must already be configured (domain, project, and either an API key or an email/password) or the run fails fast with an explanation.

Run Flags

Flags accepted by supero / python3 -m supero.cli (and passed through unchanged by ./run.sh):

Flag	Effect
--setup-only	Run project setup (env check, platform registration, schema upload, smoke tests) but do not start the server. Useful for CI or for preparing a deploy.
--server-only	Skip setup and start the server directly, using the existing .env. Fails if .env is not already configured.
--build-ui-schemas	Regenerate ui/supero-schemas.js from schemas.py / ui_schemas.py and exit. Use this after editing schema definitions when you only need the UI bundle refreshed, not a full run.
--mobile	Also set up the Expo mobile app (installs/uses Node 20 as needed) alongside the web server.
--docker	Build and run the app with Docker Compose instead of the local Python server.
--port <n>	Override the server port (defaults to PORT/UI_PORT in .env, or 5648).
--no-interactive	Use the values already in .env without prompting; required for CI.
--reset	Rebuild the local venv and re-run setup, but keep the saved .env credentials.
--reset-config	Wipe .env entirely (domain, project, credentials) and reconfigure from scratch. Asks for confirmation unless combined with --no-interactive, in which case it fails instead of prompting.
--verbose	Stream full setup/server logs to the console (they are always written to .supero-run.log regardless).
--no-seed	Skip seeding demo/test data (seeding runs by default on first setup).
--skip-tests	Skip the post-setup CRUD smoke tests and launch directly.
--version	Print the app runner version and exit.

run.sh additionally understands --verify, which runs the project’s pre-flight test bundle without needing a venv or platform connection first.

What Happens During a Run

A full run (no flags) moves through a fixed sequence of steps, printing progress for each:

•Validate project files — confirms schemas.py, config.py and setup.py exist, and detects whether the project has a web UI (ui/app.js) and/or a mobile app.
•Configure credentials — reads .env; if it is incomplete, prompts interactively for the missing pieces (an API key, or an admin email + password) and validates them against the platform before saving.
•Sync UI runtime files and generate config.js — pulls the current UI runtime layers from the installed SDK package and writes a config.js the browser reads at load time (app name, namespace, public schemas, tenant mode).
•Run setup.py — registers the domain/project if needed, uploads schemas.py to the platform, configures any services, applies access policies, and seeds demo data (unless --no-seed).
•Run CRUD smoke tests — exercises create/read/update/delete against every uploaded schema so a broken schema is caught before the server starts (skip with --skip-tests).
•Start the server — local Python server by default, or a Docker Compose stack under --docker, or the Expo mobile flow alongside it when --mobile is set.

⚠️ Docker mode does not double-register

Under --docker, the host does not run setup.py itself — the container’s own entrypoint performs registration, schema upload and smoke tests on first start (visible via docker compose logs -f). This avoids registering the domain and uploading schemas twice.

The .env File

The CLI reads and writes a project-local .env file. Values are always written double-quoted. Keys it manages:

Key	Purpose
SUPERO_URL	API base URL. Defaults to https://api.supero.dev; override only for a non-default deployment.
SUPERO_DOMAIN	The app’s domain, fixed at generation time.
SUPERO_PROJECT	The project name within that domain. Has no default — setup fails loudly rather than falling back to a shared project.
SUPERO_API_KEY	An X-API-Key style key (starts ak_). If present, the CLI skips credential prompts entirely.
SUPERO_ADMIN_EMAIL / SUPERO_PASSWORD	Email/password login, used when no API key is set. The CLI validates the password against the platform before persisting it.
PORT / UI_PORT	Local server port (default 5648).
APP_NAME / APP_EMOJI / APP_DESCRIPTION	Branding shown in the generated UI; fall back to values derived from the project if unset.
PUBLIC_SCHEMAS	Comma-separated schema types the app exposes without authentication.

🚨 Do not commit .env

It holds the app’s API key or account password. Keep it out of version control and out of Docker images you publish.

Making Schema Changes

Schemas are plain Python in the project — there is no supero schemas subcommand. Edit schemas.py (data models) or ui_schemas.py (tab/UI structure) directly, then re-run the CLI:

•A normal run (or ./run.sh) re-uploads changed schemas as part of setup.py and refreshes the UI bundle automatically.
•To only regenerate the UI schema bundle (ui/supero-schemas.js) without a full setup/server cycle, run with --build-ui-schemas.
•Use --reset to force setup.py to re-run against an existing .env (keeps credentials, re-syncs schemas); use --reset-config only when you need to change domain/project/credentials from scratch.

Connecting Your Own Cloud

For the "deploy to your own AWS or GCP" path, the same supero package ships two one-time provisioning subcommands. Run them once, in your own cloud account (Cloud Shell/CloudShell or any machine with the matching CLI installed) from the Connect wizard in the Supero dashboard:

bash

# GCP — provisions the resources Supero needs to deploy to Cloud Run in your project
supero connect-gcp --project-id my-gcp-project --external-id <from-the-wizard>

# AWS — provisions the resources Supero needs to deploy to ECS Express in your account
supero connect-aws --region us-east-1

•connect-gcp requires --project-id and --external-id (a one-time value the Connect-GCP wizard shows you); --region defaults to us-central1. Requires gcloud on PATH.
•connect-aws takes --region (default us-east-1), --stack-name (default supero-connect) and --resource-prefix (default supero). Requires the AWS CLI on PATH and deploys an inline CloudFormation template — no S3 bucket needed.

Both commands print the values to paste back into the Connect wizard once provisioning finishes. Neither command asks for, or needs, a long-lived cloud key from you.

Troubleshooting

Symptom	What to check
".env not configured" with --no-interactive	Run once without --no-interactive to complete credential setup, or make sure .env has SUPERO_DOMAIN, SUPERO_PROJECT and either SUPERO_API_KEY or SUPERO_ADMIN_EMAIL/SUPERO_PASSWORD.
Setup fails with an auth error	Re-run and re-enter the password, or switch to an API key; the CLI validates credentials before saving so a bad password will not silently persist.
CRUD smoke tests fail	The server still launches by default (a warning is printed); set SUPERO_STRICT=1 to make a failing smoke test block the launch instead. Check .supero-run.log for the failing schema/operation.
Port already in use	The CLI offers to free the port or pick the next available one; pass --port to choose explicitly, or answer the prompt under an interactive run.
Full run log	Every run appends to .supero-run.log in the project root, regardless of --verbose.

Next Steps

•Anatomy of a Supero App — what schemas.py, config.py, setup.py and ui/app.js each do in a generated project.
•Python SDK — the org.crud.* client that setup.py and your own scripts use under the hood.
•Deploy to Your Own AWS or GCP — the full Connect flow that supero connect-gcp / connect-aws are the first step of.
•Publish Your App (Go Live / Supero Cloud) — the one-click hosted alternative to running the app yourself.

← PreviousGitHub Resources & Sample Apps Next →Connect Your AI Editor over MCP

On this page