CLI Reference¶
P8s provides a powerful command-line interface for managing your projects.
Installation¶
The CLI is installed automatically with the P8s package:
Commands Overview¶
| Command | Description |
|---|---|
p8s new project <name> |
Create a new P8s project |
p8s new app <name> |
Create a new app within a project |
p8s dev |
Start development server |
p8s migrate |
Run database migrations |
p8s makemigrations |
Generate new migrations (auto-detected) |
p8s init-migrations |
Initialize migrations directory |
p8s show-migrations |
Show migration history |
p8s createsuperuser |
Create admin user |
p8s shell |
Interactive Python shell |
p8s check |
Run system checks |
p8s dbshell |
Open database shell |
p8s sendtestemail |
Test email configuration |
p8s dumpdata |
Export data to fixture |
p8s loaddata |
Import data from fixture |
p8s collectstatic |
Collect static files |
p8s seed |
Run seed script |
p8s types |
Generate TypeScript types |
p8s worker |
Start background task worker |
p8s beat |
Start periodic task scheduler |
p8s run |
Run custom management command |
p8s list-commands |
List available custom commands |
p8s version |
Show P8s version |
Project Commands¶
p8s new project¶
Create a new P8s project (now with Tailwind CSS v4 support out of the box).
Create a new P8s project with the standard directory structure.
Options:
| Option | Description |
|---|---|
--path |
Destination path |
p8s new app¶
Create a new app within your project.
Creates:
backend/apps/blog/
├── __init__.py
├── models.py
├── router.py
└── schemas.py
Development¶
p8s dev¶
Start the development server with hot-reload for both backend and frontend.
Options:
| Option | Default | Description |
|---|---|---|
--host |
0.0.0.0 |
Host to bind |
--port |
8000 |
Port for backend |
--frontend/--no-frontend |
--frontend |
Enable/disable frontend |
Output:
[backend] INFO: Uvicorn running on http://0.0.0.0:8000
[frontend] VITE ready at http://localhost:5173/
Database & Migrations¶
p8s init-migrations¶
Initialize the migrations directory with Alembic configuration.
p8s makemigrations¶
Generate a new migration with automatic model change detection.
Options:
| Option | Description |
|---|---|
-m, --message |
Migration description (required) |
--auto/--no-auto |
Auto-detect changes (default: auto) |
P8s uses Alembic under the hood and automatically:
- Imports models from all installed_apps
- Compares current models to database schema
- Generates migration with op.add_column(), op.create_table(), etc.
p8s migrate¶
Apply database migrations.
p8s show-migrations¶
Display migration history.
p8s dbshell¶
Open the database shell based on DATABASE_URL.
Opens sqlite3, psql, or mysql depending on your database.
Data Management¶
p8s seed¶
Run database seeding script using the ORM.
Options:
| Option | Description |
|---|---|
--script |
Path to the seed script |
The script should use the P8s ORM models to populate the database. The command automatically handles sys.path.
p8s dumpdata¶
Export data to a fixture file.
p8s dumpdata -o fixtures/backup.json
p8s dumpdata -m Product -m Category -o products.json
p8s dumpdata --format yaml -o data.yaml
Options:
| Option | Description |
|---|---|
-o, --output |
Output file path |
-m, --model |
Specific models to dump |
-f, --format |
Output format (json/yaml) |
p8s loaddata¶
Import data from a fixture file.
Background Tasks¶
p8s worker¶
Start the background task worker (powered by ARQ).
Options:
| Option | Default | Description |
|---|---|---|
--redis, -r |
redis://localhost:6379 |
Redis connection URL |
--queue, -q |
default |
Queues to process (repeatable) |
--max-jobs |
10 |
Max concurrent jobs |
--burst, -b |
False |
Run in burst mode (exit if empty) |
p8s beat¶
Start the periodic task scheduler.
Note: The worker process also handles periodic task execution if configured, this command is for standalone scheduling if needed.Users & Auth¶
p8s createsuperuser¶
Create an admin user for the admin panel.
Interactive prompts:
Email: admin@example.com
Password: ****
Repeat for confirmation: ****
[SUCCESS] Superuser created successfully!
Options:
| Option | Description |
|---|---|
--email |
Pre-fill email |
--username |
Optional username |
System Commands¶
p8s check¶
Run system checks to validate configuration.
Output:
Running system checks...
Checking settings... OK
Checking database... OK
Checking installed apps... OK (3 apps)
Checking admin models... OK (5 models)
Checking migrations... OK
[SUCCESS] All checks passed!
With --deploy:
- Verifies DEBUG is False
- Checks SECRET_KEY is not default
- Warns about SQLite in production
p8s sendtestemail¶
Test email configuration by sending a test email.
p8s collectstatic¶
Collect static files from apps into STATIC_ROOT.
p8s collectstatic
p8s collectstatic --clear # Clear destination first
p8s collectstatic --dry-run # Preview without copying
p8s types¶
Generate TypeScript interfaces from your backend OpenAPI schema.
Requirements:
- The command uses npx openapi-typescript, so Node.js must be available.
- You should be in the project root.
Integration: The generated file can be directly used in your frontend API client for full type safety.
p8s shell¶
Open an interactive Python shell with app context.
p8s version¶
Show the installed P8s version.
Custom Commands¶
P8s supports Django-style custom management commands.
Creating a Command¶
Create a command file in your app:
"""Send weekly reports."""
async def command():
"""Send reports to all users."""
print("Sending reports...")
# Your logic here
Running Commands¶
Environment Variables¶
| Variable | Description |
|---|---|
P8S_SETTINGS_MODULE |
Custom settings module path |
P8S_DB_URL |
Database connection string |
P8S_SECRET_KEY |
JWT secret key |
P8S_DEBUG |
Enable debug mode |
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
General error |
2 |
Command not found |