CLI Reference

Command-line entry points provided by the vibetuner package.

Package name convention

In all examples, app refers to your project's Python package (the directory under src/). The actual name depends on your project slug (e.g., src/myproject/ for a project named "myproject").

vibetuner scaffold

new

vibetuner scaffold new DESTINATION [options]

Creates a project from the local Vibetuner Copier template.

Options

• --template, -t – Use a different template source (local path, git URL, github:user/repo, etc.).
• --defaults, -d – Accept default answers for every prompt (non-interactive).
• --data key=value – Override individual template variables. Repeat for multiple overrides.
• --branch, -b – Use specific branch/tag from the vibetuner template repository.
• DESTINATION must not already exist.

Examples

# Interactive run
vibetuner scaffold new my-project
# Non-interactive defaults
vibetuner scaffold new my-project --defaults
# Override selected values in non-interactive mode
vibetuner scaffold new my-project \
--defaults \
--data project_name="My Project" \
--data python_version="3.12"

# Test from a specific branch
vibetuner scaffold new my-project --branch fix/scaffold-command

See the Scaffolding Reference for a complete description of template prompts and post-generation tasks.

update

vibetuner scaffold update [PATH] [options]

Brings an existing project up to date with the current template.

• PATH defaults to the current directory.
• --skip-answered / --no-skip-answered controls whether previously answered prompts are re-asked (defaults to skipping).
• --branch, -b – Use specific branch/tag from the vibetuner template repository.
• Exits with an error if .copier-answers.yml is missing.

adopt

vibetuner scaffold adopt [PATH] [options]

Adopts vibetuner scaffolding for an existing project that already has vibetuner as a dependency.

• PATH defaults to the current directory.
• Requires pyproject.toml with vibetuner in dependencies.
• Fails if .copier-answers.yml already exists (use update instead).

Options

• --defaults, -d – Accept default answers for every prompt (non-interactive).
• --data key=value – Override individual template variables.
• --branch, -b – Use specific branch/tag from the vibetuner template repository.

vibetuner run

Starts framework services without Docker.

dev

vibetuner run dev [frontend|worker] [--port PORT] [--host HOST] [--workers COUNT] [--auto-port]

• --auto-port – Use deterministic port based on project path (8001-8999). Mutually exclusive with --port.

# Example with auto-port (uses deterministic port 8001-8999)
vibetuner run dev --auto-port

• Sets DEBUG=1 and enables hot reload.
• service defaults to frontend.
• Frontend watches paths from paths.reload_paths and src/<project_slug>/ for changes, dynamically resolved at startup.
• Worker runs the Streaq worker with reload enabled (ignores --workers > 1).

prod

vibetuner run prod [frontend|worker] [--port PORT] [--host HOST] [--workers COUNT]

• Sets ENVIRONMENT=production.
• Disables hot reload and honors --workers for both frontend and worker services.
• Useful for containerless deployments or reproducing production settings locally.

vibetuner db

Database management commands for SQL databases (SQLModel/SQLAlchemy).

create-schema

vibetuner db create-schema

Creates all database tables defined in SQLModel metadata. This command:

1. Loads SQL models from VibetunerApp.sql_models via load_app_config() / get_all_sql_models()
2. Creates tables in the database specified by DATABASE_URL
3. Skips if tables already exist (safe to run multiple times)

Prerequisites:

• DATABASE_URL environment variable must be set
• Models must be defined using SQLModel with table=True
• Models must be listed in VibetunerApp.sql_models in your tune.py

Example:

# Set database URL
export DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb

# Create tables
vibetuner db create-schema

Note: This command is only for SQL databases. MongoDB collections are created automatically when documents are inserted.

vibetuner doctor

Validates your project setup and diagnoses common configuration issues.

vibetuner doctor

Runs diagnostic checks across eight categories and prints a colour-coded report. Exits with code 1 if any errors are found.

Check Categories

Category	What it checks
Project Structure	Root detection, .copier-answers.yml, .env file, src/ layout
App Configuration	Loads tune.py and reports import or config errors
Environment	Environment mode, SESSION_KEY strength
Service Connectivity	TCP reachability of MongoDB, Redis, R2/S3 endpoints
Models	Counts and lists registered Beanie document models
Templates	Verifies templates/ directory and checks Jinja2 syntax
Dependencies	Installed versions of vibetuner, FastAPI, Beanie, Granian, Pydantic
Ports	Availability of ports 8000 (frontend) and 11111 (worker UI)

Example Output

Project Structure
  ✓ Project root: /path/to/myproject
  ✓ .copier-answers.yml: Found
  ✓ .env file: Found
  ✓ src/ layout: Package: myapp

App Configuration
  ✓ tune.py: Loaded successfully

Environment
  ✓ Environment: development
  ! SESSION_KEY: Using default — set a unique secret in .env

Service Connectivity
  ✓ MongoDB: localhost:27017 reachable
  - Redis: REDIS_URL not configured

Models
  ✓ Registered models: 3 model(s): UserModel, OAuthAccountModel, Post

Templates
  ✓ Templates dir: Found
  ✓ Template syntax: 12 file(s) checked

Dependencies
  ✓ vibetuner: v0.5.0
  ✓ fastapi: v0.115.0
  ✓ beanie: v1.27.0
  ✓ granian: v1.7.0
  ✓ pydantic: v2.10.0

Ports
  ✓ Frontend (8000): Available
  ✓ Worker UI (11111): Available

Summary
  Passed   15
  Warnings  1
  Errors    0

Status Icons

• ✓ (green) — check passed
• ! (yellow) — warning, non-blocking issue
• ✗ (red) — error, must be fixed
• - (dim) — skipped (not applicable)

vibetuner version

Show version information.

vibetuner version [--app]

Options

• --app, -a – Show app settings version even if not in a project directory.

Custom CLI Commands

You can extend the vibetuner CLI with your own commands using AsyncTyper. Commands are registered via tune.py and namespaced under vibetuner app (or a custom name).

Setup

# src/myapp/cli/__init__.py
from vibetuner import AsyncTyper

cli = AsyncTyper(help="My app commands")

@cli.command()
async def seed(count: int = 10):
    """Seed the database with sample data."""
    from myapp.services.seeder import seed_database
    await seed_database(count)

# src/myapp/tune.py
from vibetuner import VibetunerApp
from myapp.cli import cli

app = VibetunerApp(cli=cli)

Usage

vibetuner app seed --count 50

AsyncTyper

AsyncTyper is vibetuner's extension of typer.Typer that supports async def command handlers natively. Use it instead of plain typer.Typer() so your CLI commands can call async code (database queries, HTTP requests, etc.) without asyncio.run() wrappers.

from vibetuner import AsyncTyper

cli = AsyncTyper()

@cli.command()
async def fetch_users():
    """Fetch and display all users."""
    from myapp.models import User
    users = await User.find_all().to_list()
    for u in users:
        print(u.email)

Important: Always create your own AsyncTyper() (or typer.Typer()) instance. Never re-export vibetuner.cli.app as your CLI — that is the framework's internal root app and re-registering it causes a circular reference error.

Related Commands

Generated projects expose additional helpers in the scaffolded justfile:

Development

• just local-all – Runs server + assets in parallel with auto-port (recommended for local dev)
• just local-all-with-worker – Same as above but includes background worker (requires Redis)
• just local-dev – Runs server only (use with bun dev in separate terminal)
• just worker-dev – Runs background worker only
• just update-scaffolding – Updates project to latest template

Use just --list inside a generated project to see all available commands.