ssi deploy

Deploy Command

Deploy a site from source to a destination directory.

ssi deploy <source> <deploy>

Arguments

<source> - Source directory containing your site files and ssi-config.toml
<deploy> - Destination directory for the deployed site, or - for stdout (single-file mode only)

Note: The parent of <deploy> must already exist — SSI will not create it. If <deploy> is ~/public_html/mysite, then ~/public_html/ must exist before you run ssi deploy. Create it first:
mkdir -p ~/public_html
                ssi deploy site/ ~/public_html/mysite
                

Options

--config <file> — Use a specific configuration file instead of ssi-config.toml
--single-file <file> — Process only one template and write the result (see Single-File Mode below)
--trace-tokens — Print per-token resolution trace to stderr (requires --single-file; see Token Tracing below)
--preserve-from <path> — Preserve files from this directory
--allow-external-paths — Allow external paths (symlinks outside source directory, absolute paths in config, tilde expansion in config)
--copy-method copy|hardlink|symlink — File copy method (default: copy, which uses reflink with fallback to byte copy)
--no-preserve-timestamps — Do not preserve file timestamps (applies to both copied files and processed template output)
--skip-identical — Skip copying files that are identical to the destination
--no-clobber — Fail if the target directory already exists

Per-Source Options

Individual [[step]] entries accept an options array to control copy behavior:

[[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                options = ["no-preserve-timestamps"]

Option	Description
`no-preserve-timestamps`	Do not preserve timestamps for this source
`include-dotfiles`	Include hidden files (starting with `.`)
`add-dot`	Prepend `.` to output filenames
`strip-extension`	Remove file extensions from output filenames

How it Works

The deploy command processes your site through the SSI pipeline:

Load configuration from ssi-config.toml
Process templates with emoji-based includes
Copy static assets
Output processed site to deploy directory

Timestamp Behavior

By default, SSI preserves meaningful modification times on output files:

Copied files (processing = "copy") — output mtime matches the source file mtime.
Processed templates (processing = "page") — output mtime is the maximum mtime of all contributing source files: the template itself and every filesystem include that was resolved into it. Non-filesystem includes (datetime, git, environment) do not contribute.

This means build tools and CDNs that use Last-Modified headers see accurate freshness information: a page is only considered “new” when one of its actual source files changed.

Pass --no-preserve-timestamps to suppress this behavior and let the OS assign the current time to all output files.

Single-File Mode

--single-file <file> processes one template and writes its output, leaving all other files untouched. Copy steps and preserve steps do not run. The full include resolution pipeline still runs so that per-page tokens and include sources resolve correctly.

<file> is the path to the template relative to <source>.

Use - as the destination to print the processed output to stdout instead of writing to a directory. This is useful for inspecting the processed result of one page, piping it to other tools, or integrating into a live-reload workflow.

--dry-run combined with - is a no-op restriction: stdout is not “writing files”, so output still prints.

Directory structure must already exist. Single-file mode is an incremental-update operation — it does not create directories. Run a full ssi deploy first to establish the deploy directory tree, then use --single-file to update individual pages. If a page deploys to a nested output path (e.g., blog/post.html), the blog/ directory must already exist in the deploy target, or the write will fail with a filesystem error.

# Print the processed output of one page to stdout
                ssi deploy --single-file pages/about.html site/ -
                
                # Write one processed page into a deploy directory (incremental update)
                ssi deploy --single-file pages/about.html site/ out/
                
                # Inspect and pipe through a formatter
                ssi deploy --single-file pages/about.html site/ - | tidy -q

Using - as the destination without --single-file is a fatal error.

Token Tracing

--trace-tokens (requires --single-file) prints one diagnostic line to stderr for each token replacement in the processed template, showing whether the token resolved from a page-specific file, a fallback file, or went unresolved. Stdout is not affected, so output can still be piped or redirected freely.

The trace distinguishes three outcomes:

[📝title]   page-specific: content/pages/about/title.txt
                [📝nav]     fallback:      content/nav.html
                [📝missing] UNRESOLVED

page-specific — a file was found in the per-page subdirectory (e.g. content/about/title.txt when processing about.html)
fallback — no per-page file existed; the shared default file was used instead
UNRESOLVED — the token appeared in the template but no source produced content for it

Tokens resolved from non-file sources (TOML, datetime, git, environment) are shown as resolved without a path.

Using --trace-tokens without --single-file is a fatal error. Full-site tracing would produce thousands of lines and is not useful without narrowing the scope to one template.

# Trace token resolution for one page — content to stdout, trace to stderr
                ssi deploy --single-file pages/about.html site/ - --trace-tokens
                
                # Inspect only the trace output
                ssi deploy --single-file pages/about.html site/ - --trace-tokens 2>&1 1>/dev/null

Examples

# Normal deployment
                ssi deploy site/ output/
                
                # Preview what would be deployed without making changes
                ssi --dry-run deploy site/ output/
                
                # Dry-run with verbose output to see details
                ssi -n -v deploy site/ output/
                
                # Deploy with tilde expansion and absolute paths in config
                ssi deploy ~/mysite ~/public_html --allow-external-paths

For complete argument details: ssi deploy --help