Skip to content

cli-reference.md

Latest commit

 

History

History
469 lines (328 loc) · 12.4 KB

cli-reference.md

File metadata and controls

469 lines (328 loc) · 12.4 KB

CLI Reference

Command-line entry points provided by the vibetuner package.

!!! note "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 config

Manage runtime configuration values from the command line. All subcommands require a project directory with MongoDB configured.

list

vibetuner config list

Displays a table of all registered config keys with their current values, types, sources, and categories. Secret values are masked with ********.

set

vibetuner config set KEY [--value VALUE]

Sets a config value and persists it to MongoDB.

Arguments

  • KEY — Config key to set (e.g., features.dark_mode). Must be a registered key.

Options

  • --value, -v — Value to set. When omitted for secret keys, a hidden input prompt is used (recommended to avoid shell history exposure). When omitted for non-secret keys, a regular input prompt is used.

Examples

# Set a non-secret value
vibetuner config set features.dark_mode --value true

# Set a secret value (hidden prompt, no shell history)
vibetuner config set integrations.api_key

!!! warning Passing secrets via --value exposes them in shell history. Omit --value for secret keys to use the secure hidden prompt.

delete

vibetuner config delete KEY [--yes]

Deletes a config value from MongoDB, reverting the key to its registered default.

Arguments

  • KEY — Config key to delete from MongoDB.

Options

  • --yes, -y — Skip the confirmation prompt.

Examples

# Delete with confirmation prompt
vibetuner config delete features.dark_mode

# Skip confirmation
vibetuner config delete features.dark_mode --yes

vibetuner debug

Access the debug dashboard on deployed applications using short-lived HMAC-signed links.

open

vibetuner debug open URL [--secret SECRET]

Generates a signed link that expires after 5 minutes and opens it in the default browser. On the server, the link grants an 8-hour debug session cookie.

Arguments

  • URL — Base URL of the deployed application (e.g., https://myapp.com)

Options

  • --secret, -s — Signing secret. Must match the SESSION_KEY configured on the server. When omitted, reads SESSION_KEY from the local project config (.env).

Examples

# From a project directory (reads SESSION_KEY from .env)
vibetuner debug open https://myapp.com

# From anywhere, no project checkout needed
uvx vibetuner debug open https://myapp.com --secret mysecretkey

vibetuner crypto

Manage encryption keys for OAuth app secrets stored in MongoDB. See Encrypting OAuth Secrets at Rest for background.

set-key

vibetuner crypto set-key [--key PASSPHRASE] [--env-file PATH]

Sets the encryption key and encrypts all existing plaintext secrets.

  • --key, -k — Encryption passphrase. A secure random key is generated if omitted.
  • --env-file, -e — Path to .env file (default: .env).
  • Errors if a key is already configured (use rotate-key instead).

rotate-key

vibetuner crypto rotate-key [--new-key PASSPHRASE] [--env-file PATH]

Rotates the encryption key: decrypts all secrets with the current key and re-encrypts with a new one.

  • --new-key, -k — New passphrase. Generated if omitted.
  • --env-file, -e — Path to .env file (default: .env).
  • Errors if no current key is configured (use set-key first).

vibetuner version

Show version information.

vibetuner version [--app]

Options

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

vibetuner core-templates-path

Print the absolute path to the framework's frontend templates directory on a single line. Used by frontend builds (notably vibetuner-template's setup-tw-sources script) to point Tailwind's @source directive at the package-shipped templates.

vibetuner core-templates-path
# /…/site-packages/vibetuner/templates/frontend

Output is plain stdout (logs go to stderr), so the command is safe to use in shell command substitution:

TARGET=$(uv run --frozen vibetuner core-templates-path)
ln -sfn "$TARGET" .core-templates

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.