trellis_cli
trellis_cli provides the trellis command: project scaffolding, static-site
building, local preview, and theme management. It ties the SDK together – the
engine, the
static site generator, and the theme system.
Installation
dart pub global activate trellis_cli
Or run it directly without installing:
dart pub global run trellis_cli:trellis create my_app
Quick start
Dynamic server app (Shelf + HTMX)
trellis create my_app
cd my_app
dart pub get
dart run bin/server.dart
Then open http://localhost:8080.
Static blog site
trellis create my_blog --template blog
cd my_blog
dart pub get
trellis build
trellis serve
Dart Frog app
trellis create my_frog_app --template dart_frog
cd my_frog_app
dart pub get
dart_frog dev
Relic app
trellis create my_relic_app --template relic
cd my_relic_app
dart pub get
dart run bin/server.dart
Theme scaffold
trellis create my_theme --template theme
cd my_theme
# Edit theme.yaml, layouts/, and sass/
cd example && trellis build && trellis serve
See the Theme Authoring guide for a complete walkthrough.
Commands
trellis create <project-name>
Generates a new Trellis project from a starter template.
Options:
--template(-t): the project template to use.
Available templates:
| Template | Description |
|---|---|
htmx (default) |
Shelf + HTMX counter app with Home/About pages, CSRF, security headers, and hot reload |
blog |
Static blog site built with trellis_site (Markdown content, layouts, taxonomies) |
dart_frog |
Dart Frog + HTMX counter app with file-based routing, CSRF, security headers, and hot reload |
relic |
Relic + HTMX counter app with explicit-engine wiring and security headers |
theme |
Trellis theme scaffold with theme.yaml, layouts, SASS architecture, and example preview site |
Each template generates a ready-to-run project: server or route wiring, base and
page layouts, an HTMX navigation partial, a starter stylesheet, and the standard
Dart project files (pubspec.yaml, analysis_options.yaml, .gitignore). The
blog and theme templates instead scaffold a static site and a theme
skeleton, respectively.
trellis build
Builds a static site from the current directory. Reads trellis_site.yaml for
configuration, runs the full trellis_site
pipeline, and compiles any SASS/SCSS files in the static directory.
Options:
--output(-o): output directory (default: from config, oroutput).--drafts: include draft content (default:false).--verbose(-v): show a detailed build log.
trellis build
trellis build --output dist --drafts --verbose
trellis serve
Starts a local static file server to preview a built site. Serves from the
output directory with clean-URL support (/about/ resolves to
/about/index.html).
Options:
--port(-p): port to listen on (default:8080).--output(-o): output directory to serve (default: from config, oroutput).
trellis serve
trellis serve --port 3000
trellis --version / trellis --help
Print the CLI version and usage information, respectively.
Theme management
The trellis theme subcommands manage themes for static sites built with
trellis_site. To create your own theme, see
Theme Authoring.
trellis theme add <url>
Installs a theme from a git URL or local path.
Options:
--theme: install one theme out of a multi-theme source, from itsthemes/<name>/directory.--ref: pin to a git tag or branch (recommended for production). Becomesgit clone --branch, so the ref must already exist on the remote — pick a published tag from releases. An unpushed tag fails withRemote branch <tag> not found.
# Install a built-in theme out of the Trellis repository
trellis theme add https://github.com/tolo/trellis --theme lattice --ref v0.13.0
# Install a single-theme repository (name derived from the repository)
trellis theme add https://github.com/yourname/trellis-theme-orchard
# Pin to a published release tag
trellis theme add https://github.com/tolo/trellis --theme lattice --ref v0.13.0
# Install from a local path (theme development)
trellis theme add ./path/to/my-theme
After installing, set theme: <name> in trellis_site.yaml.
trellis theme update [<name>]
Pulls the latest version of an installed theme (or all themes if no name is given).
trellis theme update
trellis theme update orchard
theme update runs git pull in the installed theme, so it applies to themes
installed from a single-theme repository. A theme installed with --theme
carries no git metadata – remove and re-add it instead.
trellis theme list
Lists all installed themes with their names, versions, and source URLs.
trellis theme info <name>
Displays the full manifest for an installed theme: name, version, author, description, features, and all params with their defaults.
trellis theme remove <name>
Removes an installed theme from themes/ and clears theme: from
trellis_site.yaml.
Project name rules
Project names must follow Dart package naming conventions:
- Lowercase letters, digits, and underscores only.
- Must start with a letter.
- Cannot be a Dart reserved word.