CLI Reference

Accent CMS uses subcommands for all operations. Run accent --help to see available commands, or accent <command> --help for details on a specific command.

Global Options

These flags are available on the top-level accent binary, before any subcommand.

Flag	Short	Description
--version	-V	Print version and git commit hash
--help	-h	Print help

accent init [PATH]

Create a new Accent CMS project with starter files.

Argument	Default	Description
PATH	. (current directory)	Directory to initialize

Creates config.yaml, a starter content page at content/01.home/default.md, and the simple theme at themes/simple/ with base templates.

# Initialize in the current directory
accent init

# Initialize in a new directory
accent init my-site

accent serve

Start the development web server.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file
--site-dir <PATH>			Project root directory (sets content and theme directories relative to it)
--content-dir <PATH>			Override content directory
--theme-dir <PATH>			Override themes directory
--theme <NAME>			Override active theme name
--address <ADDR>			Override server bind address
--port <PORT>	-p		Override server port
--production			Disable dev features (hot reload, browser reload, debug). Requires Standard or Pro license.
--tls			Enable HTTPS. Already the default in development mode, so this matters with --production or with --cert/--key.
--no-tls			Serve plain HTTP in development mode. Cannot be combined with --tls, --cert, or --key.
--cert <PATH>			Path to a PEM certificate file. Requires --tls and a Standard or Pro license.
--key <PATH>			Path to a PEM private key file. Requires --tls and a Standard or Pro license.

By default, accent serve runs in development mode with hot reload, browser auto-refresh, and the debug panel enabled. Use --production to disable all dev features for production deployments.

HTTPS in development mode

Development mode serves over HTTPS with a self-signed certificate. Production mode is unchanged and stays on plain HTTP unless you pass --tls.

Command	Protocol
accent serve	HTTPS (HTTP/2)
accent serve --no-tls	HTTP/1.1
accent serve --production	HTTP/1.1
accent serve --production --tls	HTTPS
accent serve --docs	HTTPS (HTTP/2), like accent serve
accent docs serve	HTTP/1.1, always; --no-tls is accepted

HTTPS negotiates HTTP/2, which multiplexes every request over a single connection. That matters in development because the browser reload stream is a long-lived connection: over HTTP/1.1 it permanently occupies one of the six connections a browser will open per origin, and a page loading many assets while that stream reconnects can stall waiting for a free slot.

The certificate covers localhost and 127.0.0.1 and is cached, so your browser only prompts once:

Platform	Location
macOS	~/Library/Caches/dev.accentcms/dev-cert/
Linux	$XDG_CACHE_HOME/accentcms/dev-cert/ (usually ~/.cache/...)
Windows	%LOCALAPPDATA%\accentcms\dev-cert\

On the first start the server prints the certificate path along with the command that installs it into your platform’s trust store, which removes the warning entirely. The certificate is valid for a year and is regenerated automatically when it expires, when its files no longer match their recorded digests, or when it stops covering the host names in use.

Environment variable	Effect
ACCENTCMS_DEV_CERT_DIR	Store the certificate somewhere else. Point each CI run at its own scratch directory.
ACCENTCMS_DEV_CERT_SANS	Certify extra host names, comma-separated.

Reaching the dev server from another machine

Setting server.address to 0.0.0.0 makes the server reachable across your network, but a wildcard bind is not a name a browser can ask for, so Accent cannot know which address the visitor will use. Name it explicitly:

ACCENTCMS_DEV_CERT_SANS=192.168.1.20 accent serve

Without it the server warns at startup and a phone or second machine reports a certificate name mismatch – an error mobile browsers make hard, sometimes impossible, to click past. --no-tls is the other way out.

accent serve --production --tls uses a self-signed certificate too, but never writes it down: a production serving key does not belong in a cache directory that eviction tooling and profile backups treat as disposable. Each start mints a fresh one. Use --cert/--key for a real production certificate.

Use --no-tls for a test harness or HTTP client that cannot be told to accept a self-signed certificate. It is accepted alongside --production too, where it restates the default explicitly rather than changing it.

CLI arguments take precedence over values in config.yaml.

# Start with defaults (dev mode)
accent serve

# Custom port
accent serve --port 3000

# Test with different content and theme
accent serve --content-dir ./site/content/test --theme dark

# Use a separate config file
accent serve --config staging.yaml

# Production mode
accent serve --production

# Plain HTTP in dev mode (HTTPS is the default)
accent serve --no-tls

# HTTPS in production mode with a self-signed certificate (all editions)
accent serve --production --tls

# HTTPS with custom certificates (Standard or Pro license required)
accent serve --tls --cert /path/to/cert.pem --key /path/to/key.pem

# Combine multiple options
accent serve --content-dir ./demo --theme minimal --port 8080

Serving Arbitrary Content Directories

Accent CMS can serve any directory of markdown files, not just those following CMS conventions. Use --content-dir to point at any markdown collection:

# Serve a project's docs folder
accent serve --content-dir ./docs

# Serve any markdown collection
accent serve --content-dir ~/notes

See the Getting Started guide for details on index file recognition, automatic title derivation, and template fallback.

accent service

Run the server as a Windows service, so that the site starts with Windows, restarts after a failure, and stops cleanly when Windows shuts down. accent service works only on Windows. On Linux and macOS, run accent serve --production under systemd or launchd.

Run install from an Administrator PowerShell, in the site’s directory. Everything after -- is an accent serve argument. Relative paths are stored as absolute paths, because a service starts in C:\Windows\System32, not in the site.

Set-Location C:\Sites\mysite
accent service install -- --config config.yaml --production
Start-Service accent

accent service install

Flag	Default	Description
--name <NAME>	accent	Service name. Install one service per site, each with its own name.
--display-name <TEXT>	Accent CMS (NAME)	Name shown in the Services console
--account <ACCOUNT>	virtual	virtual runs the service as NT SERVICE\NAME, an account that Windows manages and that has no password. local-service and network-service use the built-in accounts.
--start <WHEN>	auto	auto starts the service with Windows, delayed shortly after, and manual only when you start it
--env <VAR>		Pass a variable from this shell to the service. Repeat the flag for each variable.

Before it registers anything, install checks what the service will run with and prints every problem it finds. It stops when the config file does not load, a content or theme directory is missing, --production would refuse the license, or accent.exe is inside a user profile, where the service’s account cannot read it. Put accent.exe somewhere machine-wide first, such as C:\Program Files\Accent.

install then sets the service to restart 5 seconds after a failure, grants its account read access to the site and modify access to the caches and its log directory, and prints how to start it. Other services run as local-service and network-service too, so for those accounts install changes no file access and prints the access to grant yourself. To run the same checks without installing anything, use accent validate --service-check.

A service does not see the variables set in your shell, only those you pass with --env. Any local user can read those values, so keep a license key or admin token in config.yaml (license.key, admin.token) instead, and restrict who can read that file.

Running the service

Starting, stopping, and reloading a service need an Administrator PowerShell.

Task	Command
Start the service	Start-Service accent
Stop the service	Stop-Service accent
Reload config.yaml	sc.exe control accent paramchange
Show its status	Get-Service accent

The service writes its log to daily files in C:\ProgramData\accent\NAME\logs and keeps the last 14. To upgrade, stop the service, replace accent.exe, and start the service again: Windows does not let you replace a running program.

accent service uninstall

Flag	Default	Description
--name <NAME>	accent	Service to remove

Stops the service, removes the access that install granted, and removes the service. It removes only a service that install registered, and leaves any other service with that name alone. The logs stay in C:\ProgramData\accent\NAME\logs.

accent build

Generate a static site as HTML, CSS, and assets.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file
--output <PATH>	-o	output	Output directory for the built site
--clean			Remove existing output directory before building
--base-url <URL>			The URL the site is served at, used as site.url for the build (fallback: site.url from config), so the sitemap, robots.txt, feeds, canonical links, og:url, absolute_url() and JSON-LD all use it. Must be an http:// or https:// URL with no query or fragment. Its path component (e.g. /repo in https://username.github.io/repo) is the site’s base path unless --base-path or site.base_path sets one; a URL with no path builds for the root.
--base-path <PREFIX>			Explicit sub-path prefix for every internal URL Accent emits (page links, theme assets, media, search, pagination). Overrides both config and any prefix derived from --base-url/site.url. Normalized to a leading slash with no trailing slash.
--lax			Report broken internal links as warnings that do not fail the build. By default, an internal link whose target the build did not write is a build error that lists every such link with the source file to edit. The run prints how many links it relaxed. External links are not checked.
--site-dir <PATH>			Project root directory override
--content-dir <PATH>			Override content directory
--theme-dir <PATH>			Override themes directory
--theme <NAME>			Override active theme name

--base-path can be set to a prefix other than the one derived from --base-url/site.url (as in the last example below). This is allowed, but absolute URLs (sitemap, feeds, canonical links, JSON-LD) always compose --base-url/site.url with the resolved base_path appended, so --base-url https://username.github.io/repo --base-path /other produces https://username.github.io/repo/other/..., not https://username.github.io/other/.... Accent logs a startup warning when --base-path diverges from the URL’s own path this way.

The static build requires no license key.

--strict-links is deprecated: failing on a broken internal link is now the default. It is accepted, prints a notice, and is removed in 0.27.

# Build with defaults
accent build

# Build to a custom directory, cleaning first
accent build --output ./dist --clean

# Build with a base URL for sitemap and feed
accent build --base-url https://example.com

# Build a GitHub Pages project site (base path derived from the URL's path)
accent build --base-url https://username.github.io/repo

# Or set the prefix explicitly
accent build --base-url https://username.github.io/repo --base-path /repo

# Build while broken internal links are still being fixed
accent build --lax

accent validate

Validate content integrity across all pages. Checks for missing templates, broken internal links, invalid dates, orphaned pages, and missing required fields.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file
--site-dir <PATH>			Project root directory override
--content-dir <PATH>			Override content directory
--theme-dir <PATH>			Override themes directory
--theme <NAME>			Override active theme name
--templates			Validate only template syntax (skip content validation). Parses all .jinja/.j2 files and reports syntax errors.
--service-check			Check whether the site can run as a Windows service, without installing anything, as accent service install checks a service installed without --env variables. Reads --config, --content-dir, --theme-dir, and --theme, and cannot be combined with --site-dir, --templates, --models, --model, or --write-manifest. Exits with code 1 when a check fails. Windows only.
--production			With --service-check, check the site as a production service: its license, and its admin token.
--lax			Report these findings as warnings that do not fail the run: content using a plugin tag incorrectly, tags whose plugin did not load, plugin manifests that did not register, a theme that does not implement the canonical components, pages using a canonical component the theme does not implement, a video with no captions, and a link to a draft or in-review page. A name nothing declares stays an error, because it may be a misspelling. The run prints how many findings it relaxed. Cannot be combined with --write-manifest or --service-check.

# Validate all content
accent validate

# Validate with a specific config
accent validate --config prod.yaml

# Validate template syntax only (fast feedback loop)
accent validate --templates

# Relax plugin component findings while a plugin is in development
accent validate --lax

# Use in CI pipelines (exits with code 1 if problems found)
accent validate || echo "Content issues found"

# Check whether the site can run as a production Windows service
accent validate --service-check --production

accent migrate shortcodes

Rewrite [shortcode] content into {% tag %} component syntax. Reports what would change and writes nothing until you pass --write.

A shortcode is rewritten only when the theme declares a component of that name, the manifest says what its positional arguments mean, every value fits its declared type, and the printed tag parses back to what it was printed from. Everything else is left exactly as written and listed with its file, line, and reason. Shortcodes inside fenced code blocks and anything in frontmatter are never touched.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file
--content-dir <PATH>			Override content directory
--theme-dir <PATH>			Override themes directory
--theme <NAME>			Override active theme name
--write			Apply the rewrite. Without it, nothing is written.
--only <NAME>			Migrate only this component. Repeatable.
--include-frozen			Also rewrite pages in frozen documentation versions.

# See what would change
accent migrate shortcodes

# Apply it
accent migrate shortcodes --write

# One component at a time
accent migrate shortcodes --only alert --write

Pages in a frozen documentation version are reported but not rewritten: a frozen version is errata-only and its content hashes are recorded. Taking --include-frozen also means rebaselining with accent validate --write-manifest.

See Declared components for the migrate block a component manifest declares.

accent serve-static

Serve a pre-built static site from a local directory. Useful for previewing the output of accent build before deploying, or for running parity checks between the dynamic server and the static build.

Flag	Short	Default	Description
--dir <PATH>	-d	output	Directory to serve
--address <ADDR>		127.0.0.1	Server bind address
--port <PORT>	-p	4403	Server port
--base-path <PREFIX>		(resolved site.base_path)	Mount the served output under this prefix. Defaults to the resolved site.base_path, so previewing a build that was made with a base path needs no extra flags.
--tls			Enable HTTPS. Already the default, so this matters only alongside --cert/--key.
--no-tls			Serve plain HTTP. Cannot be combined with --tls, --cert, or --key.
--cert <PATH>			Path to a PEM certificate file. Requires --tls and a Standard or Pro license.
--key <PATH>			Path to a PEM private key file. Requires --tls and a Standard or Pro license.
--config <PATH>	-c	config.yaml	Path to config file (used for license key lookup only)
--open			Open the URL in the default browser after starting

serve-static defaults to HTTPS as well, using the same cached development certificate as accent serve, so a build checked with one is reached over the same scheme as with the other. Pass --no-tls for plain HTTP.

# Build then preview
accent build --clean
accent serve-static

# Serve from a custom directory on a custom port
accent serve-static --dir ./dist --port 8080

# Preview a GitHub Pages project-site build -- the prefix is picked up automatically
accent build --output ./public --base-url https://username.github.io/repo
accent serve-static --dir ./public
# Visit https://127.0.0.1:4403/repo

# Preview over plain HTTP (HTTPS is the default)
accent serve-static --no-tls

# HTTPS with custom certificates (Standard or Pro license required)
accent serve-static --tls --cert cert.pem --key key.pem

# Open the browser automatically
accent serve-static --open

accent plugin Free

Manage WASM plugins. The accent plugin commands require no license key.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Configuration file (for plugin directory)

Subcommands

Subcommand	Description
plugin list	List all installed plugins with name, version, hooks, filters, and routes
plugin info <NAME>	Show detailed plugin metadata from plugin.toml
plugin install <NAME[@VERSION]>	Install a plugin from the registry (supports version pinning)
plugin remove <NAME>	Remove an installed plugin

# List installed plugins
accent plugin list

# Show details for a plugin
accent plugin info syntax-highlight

# Install a plugin (latest version)
accent plugin install my-plugin

# Install a specific version
accent plugin install my-plugin@1.0.0

# Remove a plugin
accent plugin remove old-plugin

accent query Free

Query content, tags, and hierarchy from the command line. Requires no license key.

Shared Flags

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file
--site-dir <PATH>			Project root directory override
--content-dir <PATH>			Override content directory
--theme-dir <PATH>			Override themes directory
--theme <NAME>			Override active theme name

Subcommands

Subcommand	Description
query page <URL>	Get a single page by URL path
query list	List pages matching filter criteria
query tags [TAG]	List tags with page counts (optionally filter to one tag)
query tree	Show the content hierarchy tree
query schema	Show the content model schema
query search <TERM>	Search content by text
query validate [URL]	Validate content integrity (optionally for a single page)
query components	List the tags content may use, where each was declared, and what renders it

query page

Argument / Flag	Default	Description
URL (required)		Page URL path (e.g., /blog/my-post)
--include-content		Include raw markdown content in output
--format <FORMAT>	json	Output format: json, yaml, plain
--fields <FIELDS>		Comma-separated list of fields to include

query list

Flag	Default	Description
--tag <TAG>		Filter by tag name
--author <AUTHOR>		Filter by author
--status <STATUS>		Filter by status (published, draft, review, archived)
--path <PATH>		Filter by URL path glob (e.g., /blog/*)
--template <TEMPLATE>		Filter by template name
--language <LANGUAGE>		Filter by language code
--sort <FIELD>	date	Sort field: date, title, url, modified
--order <ORDER>	desc	Sort order: asc, desc
--limit <NUM>	50	Maximum pages to return
--offset <NUM>	0	Offset for pagination
--format <FORMAT>	json	Output format: json, yaml, plain
--fields <FIELDS>		Comma-separated list of fields to include
--nav		Show only navigation-visible pages (menu-visible, published, top-level). Sorted by menu.order then URL.

query tags

Argument / Flag	Default	Description
TAG (optional)		Filter to a specific tag name
--include-pages		Include page URLs for each tag
--format <FORMAT>	json	Output format: json, yaml, plain

query tree

Flag	Default	Description
--root <URL>	/	Root URL for subtree
--flat		Output flat list with parent references instead of nested tree
--format <FORMAT>	json	Output format: json, yaml, plain

From the site root (no --root, or --root /), on a site with several languages, each other language’s root (such as /en) is listed too, with its pages beneath it, whether or not it has a home page. The nested tree lists those roots under /; the flat list gives each its own entry with no parent. Pass --root /en for one language’s tree alone.

query schema

Flag	Default	Description
--format <FORMAT>	json	Output format: json, yaml, plain

query components

Lists the built-in tags, the theme’s components, and the tags plugins declare. For each tag, the output gives its origin (builtin, theme, or plugin), the manifest or plugin it came from, what writes its markup (engine, template, element, plugin, or nothing), whether content using it is validated, and what its body is (block, inline, or none for a tag written self-closing). A plugin tag that does not render, or is not validated, carries a note saying why. A tag a manifest declares also lists its attributes and what each holds, such as links: list of object { label: string; href?: reference }, where ? marks an attribute or field that may be left out.

Flag	Default	Description
--format <FORMAT>	json	Output format: json, yaml, plain

query search

Argument / Flag	Default	Description
TERM (required)		Search term
--in <FIELDS>	title,content,tags	Fields to search in (comma-separated). Allowed: title, content, tags, lead, frontmatter
--limit <NUM>	20	Maximum results
--format <FORMAT>	json	Output format: json, yaml, plain
--fields <FIELDS>		Comma-separated list of fields to include in results

query validate

Argument / Flag	Default	Description
URL (optional)		Validate a specific page only
--format <FORMAT>	json	Output format: json, yaml, plain

It checks frontmatter, links and each page’s document model, with structured output and optional per-page targeting. The top-level accent validate command checks more: component tags, the theme, unparseable pages and frozen content. For CI pipelines, prefer accent validate, which covers all of it and returns exit code 1 on errors.

Shared Output Options

All query subcommands support --format to control output:

• json (default) – machine-readable JSON
• yaml – human-friendly YAML
• plain – minimal plain-text output

Subcommands that return page data also support --fields to select specific fields (e.g., --fields title,url,date).

# Get details for a specific page
accent query page /blog/my-post

# Include raw markdown content
accent query page /blog/my-post --include-content

# List recent blog posts
accent query list --path "/blog/*" --limit 10

# Filter by tag and author
accent query list --tag rust --author "Jane Doe"

# List navigation-visible pages (matches the `pages` template variable)
accent query list --nav

# List all tags with page counts
accent query tags

# Show pages for a specific tag
accent query tags rust --include-pages

# Show content hierarchy
accent query tree

# Show subtree starting from /docs
accent query tree --root /docs

# Show content schema
accent query schema --format yaml

# Search across content
accent query search "getting started"

# Search only in titles and tags
accent query search "rust" --in title,tags

# Frontmatter, link and model checks (JSON report)
accent query validate

# Validate a single page
accent query validate /blog/my-post

accent docs

Generate agent-friendly documentation, template reference material, and serve the built-in documentation site.

Subcommands

Subcommand	Description
docs agent-readme	Write agent-tools-README.md command reference to the current directory
docs claude-md	Append CMS Content Operations section to ./CLAUDE.md
docs template-filters	Print all available template filters, tests, and functions to stdout
docs template-context	Print the template context reference (every variable and field with its type, generated from the context types) to stdout
docs serve	Serve the built-in documentation site from the binary, over plain HTTP; --no-tls is accepted and changes nothing

# Print filter/function reference (pipe to a file or read directly)
accent docs template-filters

# Print the template context reference
accent docs template-context

# Generate agent tool documentation
accent docs agent-readme

# Serve the built-in documentation site
accent docs serve

# Serve on a custom port
accent docs serve --port 8080

accent license

Manage license keys from the command line. Offline commands (status, activate, deactivate) work with no license key. Browser-based commands (buy, renew, refund) require a Standard or Pro license.

Flag	Short	Default	Description
--config <PATH>	-c	config.yaml	Path to configuration file

Subcommands

Subcommand	Description	Network?
license status	Show current license details (edition, org, email, expiry, status). Without --config, reads config.yaml only when the current directory has one, so it also reports a key from ACCENTCMS_LICENSE outside a site directory.	No
license activate <KEY>	Validate a JWT key and save it to config.yaml. Pass - to read from stdin.	No
license deactivate	Remove the license key from config.yaml	No
license buy	Open a checkout in the browser and receive the key via localhost callback	Yes (browser)
license renew	Open a checkout for the edition and cadence of the current license	Yes (browser)
license refund	Open the Polar.sh customer portal for refund requests	Yes (browser)

license buy

Flag	Default	Description
--edition <EDITION>	prompt	Edition to purchase: core_plus, standard, or pro. Skips the interactive selection prompt.
--cadence <CADENCE>	yearly	Billing cadence: yearly (owned – covered releases keep running after expiry) or monthly (rental – reverts to free Core after expiry).

# Show current license status (offline, works in all editions)
accent license status

# Activate a license key from email or team admin
accent license activate eyJhbGciOiJFZERTQSIs...

# Activate from stdin (CI/CD pipelines)
echo "$LICENSE_KEY" | accent license activate -

# Remove the license key (server reverts to dev mode)
accent license deactivate

# Purchase a license (opens browser, receives key via callback)
accent license buy

# Purchase a specific edition directly
accent license buy --edition standard

# Purchase on the monthly (rental) cadence instead of yearly
accent license buy --edition standard --cadence monthly

# Renew an existing license
accent license renew

# Request a refund via the Polar.sh portal
accent license refund

The buy and renew commands start a temporary localhost server to receive the license key after the browser flow completes. If the browser flow does not complete within 5 minutes, you can paste the key manually at the terminal prompt.

renew reads the edition and cadence off your current key and opens a fresh checkout for the same combination. If your subscription renewed on its own, you do not need it – the new key is emailed to you, and accent license activate <key> installs it.

Neither command talks to the payment provider directly. The browser is sent to the Accent issuance service, which creates the checkout, signs your key after payment clears, and redirects back to the one-off localhost address the command registered. The signing key never leaves that service, and the callback address is validated before any key is handed out. If the redirect does not arrive, the key is emailed to you regardless.

When the ACCENTCMS_LICENSE environment variable is set, it takes priority over the key in config.yaml. The CLI warns about this during activate and buy operations.

Environment Variables

Variable	Description	Overrides
ACCENTCMS_LICENSE	License key for Standard/Pro editions	license.key in config
RUST_LOG	Detailed log filtering using the tracing directives format	Standard Rust logging

The default log filter is accent=info,tower_http=debug. Set RUST_LOG for fine-grained control:

# Enable debug logging for all Accent CMS modules
RUST_LOG=accent=debug accent serve

# Trace-level logging for content loading
RUST_LOG=accent::content=trace accent serve

Exit Codes

Code	Meaning
0	Success
1	Content validation found problems (accent validate), or a config-load failure
2	Query error (accent query error path)