Revela

CLI Reference

Every Revela command, grouped the way revela --help and the interactive menu show them: Build, Content, Setup, Addons and Info.

Tip: Add --help to any command for its options. Run revela without arguments for the interactive menu.

Revela always works on the current folder as the project. cd into your project folder before running commands.

Editions: Commands marked Full only exist in the Full edition and the .NET global tool, but not in Standalone. Standalone has every official plugin and theme built in, so it doesn't need package management. See Installation.


Global Options

Option Alias Description
--version Show version information
--help -h, -? Show help

Build

generate

Build your site from source content.

revela generate all                  # Full pipeline
revela generate scan                 # Scan content and update the manifest
revela generate calendar             # Build calendar data from .ics files (Calendar plugin)
revela generate statistics           # Build EXIF statistics (Statistics plugin)
revela generate pages                # Render HTML pages from the manifest
revela generate images               # Process images from the manifest
revela generate images --force       # Re-encode all images, ignoring what's already done (-f)
revela generate compress             # Pre-compress output with Gzip and Brotli (Compress plugin)

generate all runs scan → calendar → statistics → pages → images. The calendar and statistics steps come from plugins, so the list can be shorter in the Full edition if those plugins aren't installed. Compression is not part of generate all; run generate compress afterwards.

If a step fails, the pipeline stops and suggests revela check.

serve

Preview the generated site on a local HTTP server (Serve plugin).

revela serve                         # http://localhost:8080
revela serve --port 3000             # Custom port (-p)
revela serve --verbose               # Log every request, not only 404s (-v)

clean

Remove generated files.

revela clean all                     # clean cache + clean output (never durable plugin data)
revela clean output                  # Remove the generated site, image files and their records, compressed files (next build re-encodes all images)
revela clean images                  # Delete unused image files (orphaned, old sizes/formats)
revela clean images --dry-run        # Preview only (-d)
revela clean cache                   # Remove data Revela rebuilds from your photos (scan, plugin data); keeps the output, so no image is re-encoded
revela clean statistics              # Remove the statistics data (Statistics plugin)
revela clean calendar                # Remove the calendar data (Calendar plugin)
revela clean compress                # Remove the .gz/.br files Revela created and their record (Compress plugin)

clean cache, clean output and clean all ask Revela and every installed plugin to remove their data of that kind, so plugins clean up after themselves. Data a plugin marks as durable (expensive or impossible to recreate) is never removed by them, only by that plugin's own clean command. See Configuration for what lives in .revela/.


Content

create page

Create an _index.revela file from a template. The path is relative to source/.

revela create page gallery "01 Galleries/Vacation" --title "Summer Vacation"
revela create page text "02 About" --title "About Me"
revela create page statistics "03 Statistics" --title "Photo Statistics"
revela create page calendar "04 Availability" --source bookings.ics --months 12
Option Alias Page types Description
--title -t all Page title
--description -d all Description (for SEO)
--sort -s gallery Sort override, e.g. dateTaken:asc
--hidden gallery, text Hide from navigation
--slug gallery, text Custom URL segment
--source -s calendar .ics file, relative to the page folder (required)
--months -m calendar Number of months to show (default 12)

Leave out the path for interactive mode:

revela create page gallery

Required options (such as --source for a calendar page) must be given: without them, create page stops with an error and exit code 1 and writes nothing. Interactive mode asks until you enter a value.

statistics and calendar come from the Statistics and Calendar plugins. See Creating Pages.

source

Download content from external sources.

revela source onedrive sync                  # Download new and changed files from OneDrive
revela source onedrive sync --dry-run        # Preview only (-n)
revela source onedrive sync --show-files     # List every affected file
revela source onedrive sync --share-url URL  # Use this share link instead of the configured one (-u)
revela source onedrive sync --force          # Re-download all files (-f)
revela source onedrive sync --clean          # Also delete local files that are gone from OneDrive (asks first)
revela source onedrive sync --clean --yes    # Delete without asking (-y); required for --clean outside a terminal
revela source onedrive sync --clean-all      # Delete ALL local files not in OneDrive, ignoring filters

revela source calendar fetch                 # Download all configured iCal feeds into source/
revela source calendar fetch --name bookings # Only one feed (-n)

See OneDrive Source and Calendar Feeds.


Setup

config

Change settings interactively (revela config) or directly with options. Most commands open prompts when you run them in a terminal without options. In scripts and CI, always pass options: config project, serve, statistics and onedrive without options then show which options to pass and exit with 1, and config site (interactive only) asks you to edit site.json directly. The plugin config commands (onedrive, serve, statistics) write project.json and need a project.

revela config                                # Interactive configuration menu

# Project
revela config project --name "My Portfolio" --url https://example.com   # -n, -u
revela config theme --set Lumina             # Select the theme (-s)
revela config theme --viewer lightbox        # Photo viewer: page, lightbox or none
revela config theme --clear-viewer           # Back to the theme's default viewer
revela config paths --source "D:\Photos" --output dist                  # -s, -o
revela config image --formats avif:75,webp:85,jpg:90                    # -f; quality 0 disables a format
revela config site                           # Site metadata in site.json (interactive only)
revela config sorting --galleries asc --field dateTaken --direction desc --fallback filename   # -g, -f, -d

# Source
revela config onedrive --share-url URL       # OneDrive share link (-u)

# Addons
revela config serve --port 3000 --verbose    # -p, -v
revela config statistics --max-entries 20 --sort-by-count false          # -m, -s

# Other
revela config locations                      # Show where configuration files and installed packages live

Package feeds (Full only):

revela config feed list                                           # List feeds
revela config feed add releases /absolute/path/to/revela-packages # Add a folder or https:// NuGet v3 URL
revela config feed remove releases                                # Remove a feed (asks when no name is given)

Remote feeds must use https://; plain http:// is only accepted for localhost. URLs with credentials (https://user:token@…) are refused, because revela.json is plain text; feed URLs in log output never show credentials or query strings.

See Configuration.

check

Check your project for problems without generating anything. Start here whenever something doesn't work.

revela check                         # Run every check (same as check all)
revela check all
revela check config                  # Configuration files and values
revela check structure               # Project structure
revela check theme                   # Theme
revela check content                 # Content and front matter
revela check slugs                   # Gallery URLs
revela check calendar                # Calendar .ics files (Calendar plugin)

Each problem comes with the file and a suggested fix. The command exits with 2 when it finds an error. Hints and warnings don't change the exit code. Checks only run when you call revela check; generate doesn't run them first, but a failing step points you to revela check.


Addons

theme

revela theme list                    # Available themes
revela theme list --online           # Also list themes from NuGet feeds (-o)
revela theme files                   # Files of the active theme and where they come from
revela theme files --theme Lumina    # A specific theme (-t)
revela theme extract Lumina          # Copy the whole theme to themes/Lumina/
revela theme extract Lumina MyTheme  # Copy it under another name
revela theme extract Lumina --file Assets/main.css   # Only a file or folder (-F)
revela theme extract Lumina --force  # Overwrite without asking (-f)

Install and remove themes (Full only):

revela theme install Lumina.Statistics       # By short name or full package ID
revela theme install --all                   # All available themes (-a)
revela theme uninstall Lumina.Statistics     # Asks for confirmation; --yes (-y) skips it

theme install accepts --version (-v), --source (-s, feed name or URL) and --allow-project-feeds, like plugin install. Installing a theme by name reads the package type from the package itself, so no packages refresh is needed; only --all and the interactive picker (no name) list themes from the package index. A plugin package passed to theme install (or a theme package passed to plugin install) is rejected with a hint to the right command.

plugin (Full only)

revela plugin list                           # Installed plugins
revela plugin install Statistics             # By short name
revela plugin install Spectara.Revela.Plugins.Statistics   # By package ID
revela plugin install Statistics --version 1.2.0           # Specific version (-v)
revela plugin install MyPlugin --source https://my-feed.example.com/v3/index.json   # Feed name or URL (-s)
revela plugin install --all                  # All available plugins (-a)
revela plugin install Statistics --allow-project-feeds     # Use project.json feeds without asking
revela plugin uninstall Statistics           # Asks for confirmation; --yes (-y) skips it

Install commands record the exact installed version under dependencies.packages in exactly one file: project.json when you run them inside a project, otherwise the global revela.json. Uninstall removes the entry from that same file.

packages (Full only)

revela packages refresh              # Update the local package index from all feeds
revela packages search               # List all packages in the index
revela packages search calendar      # Search by name
revela packages search --type theme  # Only themes or only plugins (-t theme|plugin)

restore (Full only)

Install the themes and plugins a project needs.

revela restore                       # Install missing dependencies
revela restore --check               # Only report what's missing
revela restore --allow-project-feeds # Use feeds declared in project.json without asking

Useful after cloning a project or updating Revela. Installs every package in dependencies.packages (from revela.json and project.json) that isn't installed yet, plus the package that provides theme.name. Restored versions are pinned only for entries that project.json itself declares; packages declared only in your global revela.json are installed but not copied into the project. Feeds declared only in project.json need your confirmation; non-interactive runs stop unless you pass --allow-project-feeds. See Dependencies and Feeds.


Info

revela info                          # Version, edition, runtime and active theme

In the Standalone edition revela info also lists every built-in plugin and theme with its version. In the Full edition use revela plugin list and revela theme list for the installed packages. revela --version prints just the version line, ending with the edition (— Standalone edition or — Full edition).

In the interactive menu, installing and uninstalling plugins and themes is not offered: the running menu has the package files loaded and cannot replace them safely. Run those commands from the command line (or use the setup wizard for packages that are not installed yet), then start Revela again.


Exit Codes

Code Meaning
0 Success
1 Error; see the output
2 Configuration problem (invalid JSON or setting, two plugins claiming the same plugins:<key> settings), or revela check found an error
130 Cancelled with Ctrl+C
143 Stopped by SIGTERM (for example docker stop)

Handy for scripting: treat any non-zero code as a failure. Running revela without arguments outside a terminal (for example in CI) exits with 1; always pass a command there.

Ctrl+C asks the running command to stop cleanly (revela serve shuts down its server, for example), both on the command line and for a command started from the interactive menu, which then returns to the menu. Pressing Ctrl+C a second time ends Revela immediately.

A plugin that fails to start is skipped with a warning; Revela runs without its commands and the exit code is not affected.


Automation & CI

Use the Standalone edition in CI: it's one download with everything built in, and no .NET SDK is needed. This is how revela.website itself is built:

name: Build site
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Revela (Standalone, newest release)
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          TAG=$(gh release list --repo Spectara/Revela --limit 1 --json tagName --jq '.[0].tagName')
          gh release download "$TAG" --repo Spectara/Revela --pattern "revela-linux-x64-standalone.tar.gz"
          tar -xzf revela-linux-x64-standalone.tar.gz
          chmod +x ./revela

      - name: Generate site
        run: ./revela generate all

      - uses: actions/upload-artifact@v4
        with:
          name: website
          path: output/

To pin a version for reproducible builds, replace $TAG with a tag such as v0.0.1-beta.21. The Deployment guide shows how to publish the result to GitHub Pages and other hosts.


Tab Completion (optional)

Revela is built on System.CommandLine, so your shell can tab-complete commands, subcommands, options, and enum values. It's a one-time setup per machine and shell (bash, zsh, PowerShell, but not cmd.exe):

  1. Install the dotnet-suggest global tool:

    dotnet tool install -g dotnet-suggest
    
  2. Add the dotnet-suggest shim to your shell profile. See Microsoft's tab-completion guide for the exact snippet for bash, zsh, or PowerShell.

  3. Register the Revela executable:

    dotnet-suggest register --command-path /path/to/revela
    

Restart your shell. Now revela gen<Tab> expands to generate, and revela generate <Tab> lists all, scan, pages, images, and the plugin steps.