Orionis Installer

orionis-installer creates applications from a selectable Orionis stack, with Python 3.14.x, a project-local .venv and uv.lock. Its Python module is orionis_installer and its executable is orionis.

Choose a stack, name your application, select storage and database drivers, then review the installation plan. The installer downloads the skeleton, configures the project and installs its dependencies in an independent environment. After installation, you can initialize Git, run migrations and open the project in Visual Studio Code. NO_COLOR and --no-color disable terminal colors.

Installation

Install uv and Git. Python 3.14 or newer runs the installer; uv selects stable Python 3.14.x for the application and can obtain it according to its download and network policies.

When this distribution is available on your package index:

uvx --from orionis-installer orionis new
uvx --from orionis-installer orionis new blog
uvx --python 3.14 --from orionis-installer orionis new
uv tool install --python 3.14 orionis-installer
orionis new blog
orionis --help
orionis --version

uvx --python 3.14 selects the installer's interpreter. The application has an independent environment. The framework can also provide an orionis executable; invoke the installer through uvx --from orionis-installer orionis ... and use Reactor through the application's Python. Do not overwrite existing executables with force flags.

Interactive wizard

After checking prerequisites, the wizard requests:

1. Application stack: Blank (blank_1.x, the default), SSR (ssr_1.x), Slim API (slim_api_1.x) or Slim MCP (slim_mcp_1.x).
2. Application name, defaulting to orionis-app; new blog supplies it directly.
3. Description, defaulting to A modern application built with Orionis Framework.
4. Optional author name and email.
5. File storage drivers and, for all, the default disk.
6. Database drivers and, for all, the default connection.
7. Confirmation of the absolute destination, Python target, extras, stack and source branch.

Explicit options skip their corresponding questions. After installation, the wizard asks about Git initialization (Yes), database migrations (No), and Visual Studio Code (Yes), in that order. Ctrl+C cancels with exit code 130. Without a TTY, use --no-interaction; help and version remain available.

Names use 1–100 ASCII letters, digits, dots, hyphens and underscores, with alphanumeric endpoints. Path separators, traversal, controls and reserved Windows names are rejected. Author names and descriptions support Unicode; --path supports spaces and Unicode. Invalid names are diagnosed without silent normalization. An existing destination is always rejected, even when empty.

Non-interactive use

orionis new blog --no-interaction
orionis new blog --stack Blank --no-interaction --migrate
orionis new portal --stack SSR --no-interaction --migrate
orionis new service --stack slim_api --no-interaction
orionis new tools --stack slim_mcp --no-interaction
orionis new blog --no-interaction --git --no-migrate --no-open
orionis new analytics --no-interaction --storage s3 --database redshift
orionis new team --no-interaction --storage all --database all
orionis new blog --no-interaction --path "./Project with spaces" --author-name "Jane Doe" --author-email jane@example.com

Defaults are the Blank stack, orionis-app, the description above, no author, local storage and SQLite. Aggregate driver selections default to local storage and SQLite unless specified otherwise. Git, migrations and the editor are skipped unless their positive flags are provided. This mode never requests credentials.

CLI options

--version, --no-color and --verbose are global options. --no-color and --verbose also work after new. Other options belong to new:

A default driver must be concrete. Without all, it can only repeat the selected driver. There is no destructive --force option.

Stacks

All four stacks use the official Orionis skeleton. Only the selected branch is downloaded; an unavailable branch stops installation without switching stacks.

The downloaded bootstrap determines which route files are registered. Blank and SSR register web, api, console, websocket and ai; Slim API registers only api and websocket, while Slim MCP registers only ai. All four configure the /up health endpoint. The installer preserves each branch's files. Each branch's own Orionis dependency constraint is preserved.

Drivers and configuration

Faker (for factories) and SQLite support are core dependencies in the framework manifest; the framework does not publish a factories extra. Extras are sorted and deduplicated: local + SQLite needs no extras; S3 + Redshift uses redshift,s3; both aggregate selections use database,storage. Aggregate extras install drivers while migrations use one concrete connection. Installing an SDK creates no buckets, accounts, permissions or infrastructure.

The installer preserves TOML comments, valid dependency groups, the application's version and the skeleton's Orionis requirement. The application remains unpackaged through tool.uv.package = false. .env.example is preferred; env.example is supported. Only verified configuration keys are changed, and the example remains intact. External connections and cloud storage require subsequent credential configuration. If a skeleton omits the parent directory for its declared application-local SQLite path, the installer creates that directory. The database file is created on first migration; existing files are never truncated.

Database and filesystem configuration overrides are optional. Stacks such as Slim MCP inherit Orionis defaults when those files are absent. Explicit overrides are validated, and effective drivers are verified using the project interpreter in both cases.

APP_KEY is generated by the framework using the project interpreter, without --force; existing keys are preserved. --migrate executes reactor migrate through that same interpreter after verifying the selected connection. SQLite works immediately; external databases require complete connection settings. Schema migrations run independently of seeders. To populate initial data, review the application's seeders and credentials, then invoke reactor migrate --seed manually from the generated project.

Installation and recovery

The installer clones the catalog's selected repository and branch into a sibling staging area, validates its checked-out branch and revision and removes only that clone's .git. It configures files before publication and then runs one main uv sync --python 3.14 at the final location. .venv is never moved from staging. Python, the installed Orionis distribution, extras, lockfile, APP_KEY and effective configuration are checked before reporting success.

Failures before publication clean only owned staging files. Failures after publication preserve the project and report recovery steps. The operation is not fully atomic across files, dependencies and database changes. An inherited uv workspace or custom UV_CONFIG_FILE is rejected to protect isolation; use uv's conventional configuration or documented environment variables for network, index and download policies.

Git runs only git init. It creates no commit, remote or push. Git and editor failures preserve the project; independent post-install operations still run unless cancelled. A failed migration may have changed data: inspect the database before retrying. No automatic rollback or migrate:fresh is performed.

For a preserved project, review its configuration before recovering:

cd blog
uv sync --python 3.14
uv run python -B reactor key:generate

Start a ready application:

cd blog
uv run python -B reactor serve

Apply pending schema migrations:

uv run python -B reactor migrate

After reviewing the connection and securing the seeders, populate initial data:

uv run python -B reactor migrate --seed

Validating skeletons

Run offline tests with uv run --no-sync pytest -m "not smoke". The real-branch matrix additionally requires ORIONIS_SKELETON_AUDIT to point to a directory containing separate blank, ssr, slim_api and slim_mcp checkouts of the catalog's exact branches. An unset variable skips the optional audit; a configured but incomplete directory stops the run once and names all missing branches.

Set ORIONIS_REAL_SMOKE=1 and run uv run --no-sync pytest -m smoke to exercise real installations and SQLite migrations for every stack, both with default drivers and with all drivers installed. These tests require uv, Git and network access; they do not connect to external database or cloud services.

Releasing

Keep project.version in pyproject.toml and __version__ in the package identical. After updating both, run uv lock to refresh uv.lock, then run RELEASE.ps1 from the main branch. The script rejects mismatched versions before testing, building or publishing. Before testing, it downloads every stack using the repository and branch in the source catalog, including Slim API and Slim MCP. No separate stack list or inferred branch names are used for release checkouts. CI also checks out all four branches for the real-branch matrix. It also commits and pushes project changes before publishing to PyPI. The local release script is excluded from Git; its checkout regression runs only when that script and the selected PowerShell edition are available.