Orbit CLI Reference

Orbit is Astris's artisan command-line companion for developing, scaffolding, and managing your applications.

Available Commands

Command	Description
orbit serve	Start full-stack development server with concurrent Vite HMR
orbit make:module <name>	Scaffold a complete domain module (Controller, Service, Model)
orbit make:controller <name>	Generate an Astris controller
orbit make:model <name>	Generate a SQLModel database model
orbit make:auth	Install full-stack authentication starter kit
orbit make:docker	Generate production Dockerfile and .dockerignore
orbit migrate	Run all pending database migrations
orbit make:migration "<msg>"	Auto-generate a new Alembic schema migration
orbit key:generate	Generate a new 32-byte secret APP_KEY in .env
orbit skills:install	Install or regenerate AI agent skills for the project
orbit skills:update	Re-sync AI agent skills to match installed package versions

Command Details

1. orbit serve

Launches the backend (Uvicorn) and frontend (Vite) development servers concurrently:

uv run orbit serve

• Backend: http://localhost:8000
• Vite HMR: Hot reload for Vue 3 and CSS changes without page reloads.

Production Mode (--prod)

To run in production mode (binds to 0.0.0.0, disables reload/Vite, enables multi-worker):

uv run orbit serve --prod --workers 4

2. orbit make:module <name>

Scaffolds a complete domain module with controller, service, and SQLModel schemas:

uv run orbit make:module billing

Creates:

• app/modules/billing/__init__.py
• app/modules/billing/billing_controller.py
• app/modules/billing/billing_service.py
• app/modules/billing/billing_model.py

3. orbit make:controller <name>

Scaffolds an Astris controller inside a domain module:

uv run orbit make:controller reports

Creates:

• app/modules/reports/reports_controller.py

You can also specify a custom target module:

uv run orbit make:controller payments --module billing

4. orbit make:model <name>

Scaffolds a SQLModel database table and DTO validation schemas:

uv run orbit make:model Invoice

Creates:

• app/modules/invoice/invoice_model.py

5. orbit make:auth

Scaffolds the full-stack authentication starter kit:

uv run orbit make:auth

To overwrite existing authentication files if they were previously created:

uv run orbit make:auth --force

Creates:

• app/modules/auth/auth_controller.py
• app/modules/auth/auth_service.py
• app/modules/auth/auth_model.py
• app/modules/tasks/task_controller.py
• app/modules/tasks/task_service.py
• app/modules/tasks/task_model.py
• database/migrations/versions/0001_initial_schema.py
• resources/js/Components/AstrisLogo.vue
• resources/js/Pages/Auth/Login.vue
• resources/js/Pages/Auth/Register.vue
• resources/js/Pages/Dashboard.vue

6. orbit make:migration "<message>"

Auto-generates a versioned schema migration by comparing your SQLModel models against the current database:

uv run orbit make:migration "create_articles_table"

Creates:

• database/migrations/versions/<timestamp>_create_articles_table.py

7. orbit migrate

Executes all pending database migrations against your configured DATABASE_URL:

uv run orbit migrate

To roll back the last migration:

uv run orbit migrate:rollback

To check migration status:

uv run orbit migrate:status

8. orbit key:generate

Generates a cryptographically secure 32-byte secret key and updates APP_KEY in .env:

uv run orbit key:generate

To display the generated key in the terminal without writing to .env (useful for CI/CD pipelines):

uv run orbit key:generate --show

When to use this command:

• After cloning an existing project and copying .env.example to .env.
• When provisioning a new environment (staging, production).
• When rotating application secrets for security maintenance. (Note: APP_KEY is already generated automatically when you create a project with astris new.)

9. orbit skills:install

Installs or regenerates the official Astris AI agent skill for Universal agents (.agents/skills/astris/SKILL.md):

uv run orbit skills:install

Pass --claude to install in .claude/skills/astris/SKILL.md as well:

uv run orbit skills:install --claude

10. orbit skills:update

Updates project skills to match the currently installed version of Astris:

uv run orbit skills:update

Adding AI Skills to .gitignore

Feel free to add .agents/ and .claude/ to your application's .gitignore, as these files are automatically regenerated whenever you run uv run orbit skills:install or uv run orbit skills:update.

11. orbit make:docker

Generates an optimized, multi-stage production Dockerfile and .dockerignore:

uv run orbit make:docker

Options:

• --force (-f): Overwrite existing Docker configuration files.
• --vercel: Also generate Dockerfile.vercel configured for container deployment on Vercel.

uv run orbit make:docker --vercel

Creates:

• Dockerfile: Production multi-stage build using node:24-alpine (Vite assets) and python:3.14-slim (Astral uv, non-root user astris, dynamic $PORT support).
• .dockerignore: Tailored ignore patterns for Python, Node, caches, and local secrets.
• Dockerfile.vercel (when --vercel is provided).

Next Steps

• Project generator CLI: Astris Project Generator.
• Deploying to production: Production & Docker.