CLI Commands

This page documents StaticForge's command-line interface, including all built-in commands, their options, and usage patterns. The CLI is the primary interface for building, auditing, and managing StaticForge sites.

For information about the event system that commands interact with, see Event System. For configuration options that commands use, see Configuration System.

---

Command Architecture Overview

StaticForge's CLI is built on Symfony Console and implements a two-tier command registration system: core commands are registered directly in the bootstrap, while feature commands are registered dynamically via the CONSOLE_INIT event.

Command Registration Flow

Sources:

• bin/staticforge.php1-79

Command Class Hierarchy

StaticForge commands extend Symfony's Command class and follow a consistent structure:

Sources:

• src/Commands/InitCommand.php1-238
• src/Commands/Audit/ConfigCommand.php1-210
• src/Commands/Audit/ContentCommand.php1-258
• src/Commands/Audit/LiveCommand.php1-389
• src/Commands/Make/HtaccessCommand.php1-103

---

Core Command Registration

Core commands are registered directly in the CLI bootstrap sequence, ensuring they are always available regardless of feature configuration.

Command	Class	Purpose
site:init	InitCommand	Initialize new project structure
audit:config	ConfigCommand	Validate configuration completeness
audit:content	ContentCommand	Validate content file integrity
audit:links	LinksCommand	Validate internal and external links
audit:live	LiveCommand	Audit deployed site security and performance
audit:seo	SeoCommand	Validate SEO metadata and structure
make:htaccess	HtaccessCommand	Generate production .htaccess file

Sources:

• bin/staticforge.php64-70

---

Site Commands

site:init - Project Initialization

Initializes a new StaticForge project by creating the standard directory structure, configuration files, and sample content.

Usage:

Options:

Option	Description
--force, -f	Overwrite existing files

Execution Flow:

Directory Structure Created:

Directory	Purpose
content/	Source content files (Markdown, HTML)
templates/	Twig template files
public/	Generated static site output
config/	Additional configuration files
logs/	Application log files

Configuration Files Created:

File	Source	Purpose
.env	.env.example	Environment-specific configuration
siteconfig.yaml	siteconfig.yaml.example	Site structure and metadata
content/index.md	Generated	Sample homepage content

Template Resolution:

The command searches for bundled templates using a multi-path strategy:

1. Development mode: __DIR__ . '/../../'
2. Installed as dependency: getcwd() . '/vendor/eicc/staticforge/'
3. Alternative vendor structure: __DIR__ . '/../../../../../eicc/staticforge/'

Force Behavior:

Without --force, the command preserves existing files and displays notes:

• Existing directories are skipped
• Existing .env and siteconfig.yaml are preserved
• Existing template files are not overwritten

With --force, all files are overwritten, enabling project reinitialization.

Sources:

• src/Commands/InitCommand.php28-75
• src/Commands/InitCommand.php77-89
• src/Commands/InitCommand.php91-112
• src/Commands/InitCommand.php114-135
• src/Commands/InitCommand.php137-186
• src/Commands/InitCommand.php220-237

---

Audit Commands

Audit commands validate project integrity at multiple levels: configuration, content, links, live deployment, and SEO. These commands support CI/CD integration and quality assurance workflows.

audit:config - Configuration Validation

Validates project configuration by checking environment variables, site configuration, and feature requirements.

Usage:

Validation Layers:

Core Configuration Checks:

Check	Type	Location	Requirement
SITE_BASE_URL	Environment	.env	Required
TEMPLATE	Environment/Config	.env or siteconfig.yaml	Required
site.name	Configuration	siteconfig.yaml	Best practice
content/	Filesystem	Project root	Directory must exist
templates/	Filesystem	Project root	Directory must exist
.env	Filesystem	Project root	File must exist

Feature Configuration Checks:

For each feature implementing ConfigurableFeatureInterface, the command validates:

1. Required Config Keys: Dot-notation paths in siteconfig.yaml (e.g., search.engine)
2. Required Environment Variables: Keys that must exist in $_ENV, getenv(), or $_SERVER
3. Configuration Help: If validation fails, displays example configuration from getConfigHelp()

Example Feature Check (Search):

Output Format:

Configuration Audit
===================

Core Configuration
------------------
[INFO] Found .env file.

Environment
-----------
[INFO] Found .env file.

Feature Configuration
---------------------
Scanned 5 configurable features.

Audit Summary
=============

[ERROR] Found 2 configuration errors.

Core
----
 [MISSING CONFIG] Missing 'SITE_BASE_URL' in environment (.env).

Feature: Search
---------------
 [CONFIG] Missing key in siteconfig.yaml: search

Example Configuration:
search:
 engine: minisearch

Exit Codes:

• 0 (SUCCESS): No errors found
• 1 (FAILURE): One or more errors found

Sources:

• src/Commands/Audit/ConfigCommand.php33-194
• src/Commands/Audit/ConfigCommand.php196-209
• src/Features/Search/Feature.php35-55

audit:content - Content Integrity Validation

Scans source content files for frontmatter validity, taxonomy consistency, and broken internal links.

Usage:

Validation Checks:

Frontmatter Validation:

Check	Type	Description
YAML Syntax	Error	Frontmatter must be valid YAML between --- delimiters
Required Fields	Error	title field must be present
Draft Status	Warning	Files with draft: true are flagged

Link Validation:

Link Type	Validation
External (http, https)	Skipped
Email (mailto:)	Skipped
Telephone (tel:)	Skipped
Anchors (#fragment)	Skipped
Generated (.html extension)	Skipped (validated by audit:links post-build)
Internal relative	Resolved relative to current file, checked with file_exists()
Internal absolute (/path)	Resolved relative to content/ directory

Path Resolution Logic:

Link: ../images/diagram.png
Current file: content/blog/post.md
Resolved path: content/blog/../images/diagram.png
 → content/images/diagram.png

Link: /assets/style.css
Current file: content/docs/page.md
Resolved path: content/assets/style.css

Output Format:

Content Audit
=============

Found 15 Content files to audit.

Checking Frontmatter...
Checking Markdown Internal Links...

Content Issues
==============

content/blog/post.md
--------------------
 [ERROR] Missing required field: title
 [WARNING] Post is marked as draft

content/docs/guide.md
---------------------
 [ERROR] Link target not found: ../missing.png

Audit Summary
=============
Files Scanned: 15
Errors: 2
Warnings: 1

Exit Codes:

• 0 (SUCCESS): No errors (warnings are tolerated)
• 1 (FAILURE): One or more errors found

Sources:

• src/Commands/Audit/ContentCommand.php38-117
• src/Commands/Audit/ContentCommand.php119-180
• src/Commands/Audit/ContentCommand.php193-257

audit:live - Live Site Validation

Performs remote validation of a deployed site, checking SSL certificates, security headers, performance optimizations, and deployment integrity.

Usage:

Options:

Option	Description
--url, -u	Target URL to audit (overrides UPLOAD_URL from .env)

Audit Categories:

Connectivity & SSL Checks:

Check	Type	Condition	Result
SSL Certificate Expired	Error	validTo_time_t < time()	Certificate expired
SSL Certificate Expiring Soon	Warning	validTo_time_t - time() < 14 days	Certificate expires in N days
SSL Certificate Valid	Success	validTo_time_t - time() >= 14 days	Certificate valid for N days
No HTTPS	Warning	scheme !== 'https'	Site not using HTTPS

Security Header Checks:

Header	Expected Value	Missing Result
Strict-Transport-Security	Any value	Warning (HTTPS sites only)
X-Content-Type-Options	nosniff	Warning
X-Frame-Options	Any value	Warning

Performance Header Checks:

Header	Expected Value	Missing Result
Content-Encoding	gzip, deflate, or br	Warning
Cache-Control	Any value	Warning
ETag or Last-Modified	Any value	Warning

Deployment Integrity Checks:

Resource	Check	Expected	Missing Result
robots.txt	HTTP Status	200	Warning
sitemap.xml	HTTP Status	200	Warning
sitemap.xml	Content-Type	Contains xml	Warning

Output Format:

Live Site Audit
===============

Auditing target: https://example.com/

 > Checking connectivity and SSL...
 > Checking security headers...
 > Checking performance headers...
 > Checking deployment integrity...

Live Audit Results
==================
 [SUCCESS] [SSL] SSL Certificate is valid for 89 days.
 [SUCCESS] [Security] 'Strict-Transport-Security' header found.
 [SUCCESS] [Security] 'X-Content-Type-Options: nosniff' header found.
 [SUCCESS] [Security] 'X-Frame-Options' header found.
 [SUCCESS] [Performance] Content-Encoding enabled (gzip).
 [SUCCESS] [Performance] 'Cache-Control' header found.
 [SUCCESS] [Performance] Cache validator found (ETag).
 [SUCCESS] [Integrity] robots.txt found.
 [SUCCESS] [Integrity] sitemap.xml found and appears valid.

Audit Summary
=============
Errors: 0
Warnings: 0
Passed Checks: 9

CURL Configuration:

The command uses cURL with the following defaults:

• CURLOPT_TIMEOUT: 10 seconds
• CURLOPT_SSL_VERIFYPEER: false (allows self-signed certificates for testing)
• CURLOPT_SSL_VERIFYHOST: false
• CURLOPT_FOLLOWLOCATION: true (follows redirects)

Exit Codes:

• 0 (SUCCESS): No errors (warnings are tolerated)
• 1 (FAILURE): One or more errors found (connectivity failures, expired certificates)

Sources:

• src/Commands/Audit/LiveCommand.php34-125
• src/Commands/Audit/LiveCommand.php130-198
• src/Commands/Audit/LiveCommand.php200-258
• src/Commands/Audit/LiveCommand.php260-304
• src/Commands/Audit/LiveCommand.php306-356
• src/Commands/Audit/LiveCommand.php358-388

audit:links and audit:seo

These commands are registered in the bootstrap but their implementations are not provided in the available source files. Based on the registration pattern:

• audit:links: Validates links in generated HTML output (post-build validation)
• audit:seo: Validates SEO metadata, meta tags, and structured data

Sources:

• bin/staticforge.php67-69

---

Make Commands

make:htaccess - .htaccess Generator

Generates a production-ready .htaccess file with security headers, performance optimizations, and StaticForge-specific protections.

Usage:

Options:

Option	Description	Default
--write, -w	Write output to file instead of stdout	(disabled)
--output, -o	Output filename when using --write	htaccess.txt

Generated Configuration:

Protection Rules:

Rule	Directive	Purpose
Manifest Protection	<Files "staticforge-manifest.json">	Deny access to build metadata
Require all denied

Security Headers:

Header	Value	Purpose
Strict-Transport-Security	max-age=31536000; includeSubDomains	Enforce HTTPS for 1 year
X-Content-Type-Options	nosniff	Prevent MIME-type sniffing
X-Frame-Options	SAMEORIGIN	Prevent clickjacking

Caching Strategy:

Content Type	Cache Duration	Assets Covered
HTML/Data (default)	1 hour (3600s)	All files not matched below
Static Assets	1 week (604800s)	.ico, .pdf, .flv, .jpg, .jpeg, .png, .gif, .svg, .webp, .js, .css, .woff, .woff2, .ttf

Output Behavior:

Without --write:

• Prints .htaccess content to stdout
• Displays usage tip: Use --write to save this content to htaccess.txt
• Returns SUCCESS

With --write:

• Writes content to specified file (default: htaccess.txt)
• Displays success message or error
• Warns if overwriting existing .htaccess

Safety Note:

The command defaults to htaccess.txt rather than .htaccess to prevent accidental overwriting of existing server configuration. Users must manually rename or copy the file to .htaccess after review.

Usage Examples:

Sources:

• src/Commands/Make/HtaccessCommand.php35-102

---

Feature Command Registration

Features can register custom commands by listening to the CONSOLE_INIT event during bootstrap. This pattern enables features to contribute commands without modifying core code.

CONSOLE_INIT Event Flow

Event Parameters:

The CONSOLE_INIT event receives:

• application: The Symfony Console Application instance

Example: RenderSiteCommand Registration

Common Feature Commands:

Command	Feature	Purpose
site:render	Renderer	Build static site from content
site:devserver	DevServer	Launch local development server
site:upload	Upload	Deploy site to remote server
feature:setup	FeatureManager	Configure external features

Sources:

• bin/staticforge.php72-76

---

Command Development Patterns

Container Access Pattern

Commands that need access to configuration and services receive the Container instance via constructor injection:

Sources:

• src/Commands/Audit/ConfigCommand.php20-26

SymfonyStyle Usage Pattern

Commands use SymfonyStyle for consistent, formatted output:

Output Methods:

Method	Purpose
title()	Display command title
section()	Display section header
text()	Display regular text
note()	Display informational note (blue)
success()	Display success message (green)
error()	Display error message (red)
warning()	Display warning message (yellow)
listing()	Display bulleted list
table()	Display formatted table
writeln()	Write line with custom formatting
newLine()	Insert blank line

Sources:

• src/Commands/Audit/ConfigCommand.php33-36
• src/Commands/InitCommand.php30-31

Error Grouping Pattern

Commands that perform multiple checks group errors by scope or file for readable output:

Sources:

• src/Commands/Audit/ConfigCommand.php176-191
• src/Commands/Audit/ContentCommand.php91-109

File System Scanning Pattern

Commands that process files use RecursiveDirectoryIterator for efficient traversal:

Sources:

• src/Commands/Audit/ContentCommand.php54-59
• src/Commands/Audit/ContentCommand.php123-129

HTTP Request Pattern (LiveCommand)

Commands that audit remote sites use cURL with consistent configuration:

Sources:

• src/Commands/Audit/LiveCommand.php130-198

---

Testing Commands

Commands are tested using Symfony's CommandTester class, which captures output and provides assertion methods.

Command Test Structure

CommandTester Methods:

Method	Purpose
execute(array $input)	Execute command with options/arguments
getStatusCode()	Get command exit code
getDisplay()	Get command output as string
getInput()	Get command input object
getOutput()	Get command output object

Sources:

• tests/Unit/Commands/InitCommandTest.php29-47
• tests/Unit/Commands/InitCommandTest.php49-64
• tests/Unit/Commands/InitCommandTest.php66-82

---

Complete Command Reference:

Command	Type	Status	Purpose
site:init	Core	Available	Initialize project structure
site:render	Feature	Via CONSOLE_INIT	Build static site
site:devserver	Feature	Via CONSOLE_INIT	Launch development server
site:upload	Feature	Via CONSOLE_INIT	Deploy to remote server
audit:config	Core	Available	Validate configuration
audit:content	Core	Available	Validate content integrity
audit:links	Core	Registered	Validate links (implementation not shown)
audit:live	Core	Available	Audit deployed site
audit:seo	Core	Registered	Validate SEO (implementation not shown)
make:htaccess	Core	Available	Generate .htaccess file
feature:setup	Feature	Via CONSOLE_INIT	Configure external features