Skip to content

Command-Line Tools for Authors

VIBE comes with powerful command-line tools that can help you develop and debug templates faster. You run them from your terminal in the root directory of the VIBE application.

Running the Server (run)

Starts the VIBE web server so you can test your templates in a browser.

vibe run

By default, the server starts on port 5001 with debug mode enabled. You can customize this:

vibe run --port 8000         # Use a different port
vibe run --no-debug          # Disable debug mode
vibe run --use-reloader      # Auto-restart when files change

Once running, open http://127.0.0.1:5001/ (or your custom port) in a web browser to see the template selection page.

Creating a New Template (create)

Generates a new template skeleton with a starter config.yml and template.md, and registers it in the main config.yml.

vibe create "My New Template"

This creates a folder under templates/my-new-template/ with a basic working template that you can start editing right away. The template name is automatically converted to a URL-friendly slug.

Validating Templates (validate)

This is the most important tool for an author. It runs a full static analysis on your template and questions, checking for common errors like undefined variables, mismatched types, and invalid syntax.

How to Run:

  • Validate all templates:

    vibe validate

  • Validate a single, specific template:

    vibe validate my_template_id

    (Where my_template_id is the ID you used in the main config.yml TEMPLATE_SOURCES block).

Options:

  • --details or -d: Show detailed error and warning messages with line numbers.
  • --verbose or -v: Show debug/info logs during validation.

Example Output:

INFO --- Validation Summary ---
INFO All targeted template(s) validated successfully. count=1

If errors are found, they will be printed with the file name and line number, helping you fix them quickly. Running validate often can save you a lot of time.

Validating Components (validate-components)

This command works just like validate, but it specifically targets and validates your reusable components.

How to Run:

  • Validate all discovered components:

    vibe validate-components

  • Validate a single component:

    vibe validate-components clauses.indemnity

  • Validate components within a specific template:

    vibe validate-components --template my_template

Inspecting Saved State (inspect)

Sometimes a user might send you a .vibestate file that they saved from an interview. The inspect tool lets you securely open and view the contents of this file to see exactly what answers they provided.

How to Run:

vibe inspect /path/to/the/user_file.vibestate

Output: The tool will print a clean summary of the saved state, including:

  • The template ID and version.
  • Which questions were asked.
  • A neatly formatted list of all the answers in the current_state.

Security Warning: By default, inspect verifies the file's digital signature to ensure it hasn't been tampered with. If the signature is invalid, it will refuse to open the file. If you are absolutely certain the file is from a trusted source and want to inspect it anyway, you can use the --no-verify flag, but do so with extreme caution.

Testing Template Expressions (eval)

An interactive environment for testing Jinja expressions against your template's questions and data. This is useful for verifying that your template logic works as expected before running the full server.

How to Run:

vibe eval --template my_template

This opens an interactive prompt where you can type Jinja expressions and see their output immediately:

(vibe)> `{{ client_name.upper() }}`
ACME CORP
(vibe)> `{{ "item" | plural(if_=3) }}`
items

Options:

  • --template or -t: Load a template's questions as context variables.
  • --state or -s: Load a .vibestate file to use real saved answers.
  • --set VAR=VALUE: Set a variable value (repeatable, supports dot notation like --set 'address.city=Stockholm').
  • --locale or -l: Set the locale for linguistic filters (e.g., --locale sv).

Interactive Commands:

Command Description
$vars List all variables in the current context
$questions Show the template's question definitions
$context Pretty-print the full context tree
$locale Show the current locale
$locale = sv Change the locale dynamically
$reload Reload the template and/or state from disk
$help Show all available commands
$exit Exit the REPL

Scaffolding UI Overrides (scaffold)

Copies stock UI template files or CSS into your template bundle so you can customize them. This saves you from having to find and copy the built-in files manually.

How to Run:

  • List available files you can override:

    vibe scaffold my_template --list

  • Copy specific files into your template's override folder:

    vibe scaffold my_template layout/standard.html
vibe scaffold my_template theme.css

  • Overwrite existing overrides:

    vibe scaffold my_template layout/standard.html --force

After scaffolding, edit the copied files in your template's ui/ directory. See the UI Customization Guide for details on what you can override and how.