CLI Overview

Suprnova ships two binaries with different jobs. The global suprnova - installed once into ~/.cargo/bin - scaffolds new projects, generates code, boots dev servers, and runs migrations. The per-project console, built from each app's src/bin/console.rs, runs runtime commands that need the app's compiled types (seeders, pruners, your own #[command] handlers). This chapter is the map; each subcommand has its own deep-dive in the sibling chapters listed under Next.

Install

The CLI is distributed via cargo install --git. Suprnova is distributed through git tags, not crates.io - see Distribution model.

cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.0.3 suprnova-cli
suprnova --version

To upgrade later, pass --force:

cargo install --force --git https://github.com/eas4ai/suprnova.git --tag v4.0.3 suprnova-cli

The two binaries

Worker daemons (schedule:run, schedule:work, schedule:list, workflow:work, queue:work) sit on a third surface: your app binary's own clap parser, the same binary that serves HTTP. The global suprnova shells into cargo run --quiet -- <name> for those so you can launch them from the CLI you already have open. See Console for the full three-way split.

Why Suprnova diverges

Laravel solves this with a single per-project script - php artisan - because PHP loads framework and user code together at runtime. Rust links binaries at compile time, so a global suprnova binary can't statically see your seeders, factories, or #[command] handlers. The pragmatic split:

• File-only work (scaffolding, generators, ops) lives on the global suprnova binary
• Runtime work that needs your compiled types lives on the per-project console binary
• Daemons live on your app/server binary so they share the same boot path as serve

You get the ergonomics of php artisan (cargo run --bin console -- db:seed or console <name> directly) without the static-linking lie.

Commands at a glance

The same list suprnova --help prints, grouped the same way.

Create

Generate

See Generators for the full scaffold details and what each generated file looks like.

Live

live:add and live:registry start no process: nothing a component carries runs while they fetch, check, sign or install it.

live:check, live:inspect, and live:assets run inside your application: the CLI starts cargo run --bin console and reads a bounded, versioned JSON-lines report from the framework's hidden tooling helper, so it never needs a framework dependency of its own. Build output stays on stderr; anything unexpected on stdout fails the command closed.

Database

db:seed and model:prune run your project's console binary (cargo run --quiet --bin console -- <name>), because the seeder and model registries are compiled into your crate. The CLI checks no name: the console binary knows which seeders and models exist, and it reports an unknown one. You can also run them directly, for example cargo run --bin console -- db:seed or ./target/debug/console db:seed. See Console for the registration pattern.

See Migrations chapter for the full migration workflow.

Schedule

Each of these shells into cargo run --quiet -- <name> against your app/server binary - the same binary that serves HTTP - so registered tasks and bootstrapped services are visible. See Scheduling CLI and the Scheduling chapter.

Workflow

See Workflows.

SSR

Each of these runs cargo run --bin <app> -- <name> from the project directory, the way serve runs the backend, and exits with the application's status. The CLI reads no SSR settings of its own: the configuration your application passes to Inertia::install decides what each command checks and does, as Console describes.

See Inertia SSR for the production setup.

Deploy

See Docker and the Deployment chapter.

Security

See Encryption for what APP_KEY protects and how rotation via APP_KEY_PREVIOUS works.

Quick start

The most common path from "nothing installed" to "running app":

# 1. Install the CLI
cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.0.3 suprnova-cli

# 2. Scaffold a project (interactive - picks Svelte by default)
suprnova new my-app

# 3. Boot it
cd my-app
suprnova migrate
npm install
suprnova serve

Non-interactive scaffold (CI, scripted setup):

suprnova new my-app \
  --frontend svelte \
  --no-interaction \
  --no-git

API-only scaffold (no Inertia, no SPA):

suprnova new my-api --api

Generate code in an existing project:

suprnova make:controller Posts
suprnova make:migration create_posts_table
suprnova make:command reports:daily   # registers under the per-project console binary
suprnova migrate

Getting help

--help (or -h) works on any subcommand. The top-level help is hand-formatted (ui::print_help) and groups commands by section; the per-subcommand help comes from clap and shows every flag with its default:

suprnova --help
suprnova new --help
suprnova serve --help
suprnova make:inertia --help

For the per-project console binary:

cargo run --bin console -- --help
cargo run --bin console -- db:seed --help
cargo run --bin console -- <your-command> --help

--version prints the version on its own line, which is what you want when reporting a bug or checking whether an install took:

suprnova --version
# suprnova 4.0.3

Both -v and -V are accepted. Clap's generated flag offers only -V; this one is hand-declared so the lowercase spelling - the one most people try first - works too. The version also appears in the --help banner, which is where it lived before the flag existed.

Next

• suprnova new - every flag the scaffolder accepts and the directory layout it produces
• suprnova serve - the dev runner: backend + Vite + type generation
• Generators - the full make:* family with output templates
• Migrations CLI - migrate, migrate:fresh, db:sync, and the SeaORM workflow
• Console - the per-project console binary, #[command], #[derive(Command)], and the three-binary asymmetry
• Installing Live Components - live:add, its plan, and the record in suprnova.toml
• Live Component Libraries - live:registry new, check, sign and rotate-key