Site Commands

This document covers the core site management commands provided by StaticForge: site:init, site:render, site:devserver, and site:upload. These commands handle project initialization, site generation, local development, and deployment workflows.

For information about quality validation commands, see Audit Commands. For utility commands that generate deployment artifacts, see Make Commands.

---

Command Registration Architecture

StaticForge uses Symfony Console as its CLI framework. Commands are registered through a two-phase process: core commands are registered directly in the CLI entry point, while feature-specific commands register themselves via the CONSOLE_INIT event.

CLI Entry Point Registration Flow

Sources: bin/staticforge.php1-79

Core vs Feature Commands

Command	Registration Method	Implementation Location	Purpose
site:init	Direct registration	src/Commands/InitCommand.php	Project initialization
audit:config	Direct registration	src/Commands/Audit/ConfigCommand.php	Configuration validation
audit:content	Direct registration	src/Commands/Audit/ContentCommand.php	Content validation
audit:links	Direct registration	src/Commands/Audit/LinksCommand.php	Link validation
audit:live	Direct registration	src/Commands/Audit/LiveCommand.php	Live site audit
audit:seo	Direct registration	src/Commands/Audit/SeoCommand.php	SEO validation
make:htaccess	Direct registration	src/Commands/Make/HtaccessCommand.php	Generate .htaccess
site:render	Feature event (CONSOLE_INIT)	src/Features/SiteBuilder/Commands/RenderSiteCommand.php	Site generation
site:devserver	Feature event (CONSOLE_INIT)	Feature implementation	Development server
site:upload	Feature event (CONSOLE_INIT)	Feature implementation	Site deployment

Sources: bin/staticforge.php41-76

---

site:init Command

The site:init command initializes a new StaticForge project by creating the necessary directory structure, copying bundled templates, and creating configuration files from examples.

Command Signature

Options

Option	Short	Description
--force	-f	Overwrite existing files without prompting

Directory Structure Created

Sources: src/Commands/InitCommand.php36-51

Initialization Process

The InitCommand::execute() method performs initialization in the following sequence:

Sources: src/Commands/InitCommand.php28-75

File Creation Methods

1. Directory Creation

The command creates five standard directories using mkdir() with 0755 permissions:

src/Commands/InitCommand.php44-51

2. Bundled Template Copy

Templates are copied from the StaticForge package installation using recursiveCopy():

src/Commands/InitCommand.php77-89 src/Commands/InitCommand.php188-218

The findVendorPath() method searches multiple locations to support both development and installed scenarios:

src/Commands/InitCommand.php220-237

3. Environment File Creation

The .env file is created from .env.example if available:

src/Commands/InitCommand.php91-112

4. Site Configuration File Creation

The siteconfig.yaml file is created from siteconfig.yaml.example:

src/Commands/InitCommand.php114-135

5. Sample Content Creation

A welcome page is created at content/index.md with frontmatter:

src/Commands/InitCommand.php137-186

Force Option Behavior

When --force is not specified:

• Existing files are not overwritten
• User is notified with "already exists" messages

When --force is specified:

• All files are overwritten regardless of existence
• Useful for resetting a corrupted project structure

Sources: src/Commands/InitCommand.php101-104 src/Commands/InitCommand.php124-127 src/Commands/InitCommand.php141-144

---

site:render Command

The site:render command generates the complete static site by processing all content files through the event-driven pipeline and applying templates.

Command Signature

Options

Option	Short	Type	Description
--clean	-c	None	Remove all files from output directory before generation
--template	-t	Value	Override template (e.g., sample, staticforce)
--input	-i	Value	Override input/content directory path
--output	-o	Value	Override output directory path

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php30-55

Render Execution Flow

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php58-171

Event Pipeline Display

When run with verbose mode (-v), the command displays the complete event pipeline:

src/Features/SiteBuilder/Commands/RenderSiteCommand.php122-136

Output format:

Event Pipeline:
 1. CREATE - Initialize features
 2. PRE_GLOB - Prepare for file discovery
 3. POST_GLOB - Process discovered files
 4. PRE_LOOP - Before render loop
 5. RENDER LOOP - Process each file
 - PRE_RENDER
 - RENDER
 - POST_RENDER
 6. POST_LOOP - After render loop
 7. DESTROY - Cleanup

Directory Override Behavior

The command supports runtime directory overrides that take precedence over configuration:

1. Input Directory Override (--input):
   • Validates directory existence before processing
   • Updates SOURCE_DIR container variable
   • Throws exception if directory does not exist

src/Features/SiteBuilder/Commands/RenderSiteCommand.php92-97

2. Output Directory Override (--output):
   • Updates OUTPUT_DIR container variable
   • Directory is created automatically if missing

src/Features/SiteBuilder/Commands/RenderSiteCommand.php99-101

Clean Option Implementation

The --clean option removes all existing files from the output directory before generation:

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php108-118 src/Features/SiteBuilder/Commands/RenderSiteCommand.php255-268

The recursive directory removal is implemented in removeDirectory():

src/Features/SiteBuilder/Commands/RenderSiteCommand.php273-291

Verbose Mode Statistics

When run with verbose mode (-v or -vv), the command displays detailed statistics after generation:

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php197-248

The statistics are pulled from container variables:

• discovered_files: Array of all processed files
• features: Array of loaded feature metadata

Template Override Mechanism

Template override allows switching between different template collections at runtime:

src/Features/SiteBuilder/Commands/RenderSiteCommand.php66-71 src/Features/SiteBuilder/Commands/RenderSiteCommand.php89

The override is passed to the Application constructor, which validates template existence and falls back to configured template if invalid.

Error Handling

The command implements comprehensive error handling:

1. Input Directory Validation:

   • Throws Exception if specified input directory does not exist
   • Message: "Input directory does not exist: {path}"

2. Generation Failure:

   • Catches exceptions from Application::generate()
   • Displays error message and stack trace in verbose mode
   • Returns Command::FAILURE exit code

3. Missing Configuration:

   • Throws RuntimeException if OUTPUT_DIR not set in container

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php158-170

---

site:devserver Command

The site:devserver command starts a local PHP development server to preview the generated static site. This command is registered by a feature via the CONSOLE_INIT event.

Expected Usage

Typical Implementation

While the implementation file is not provided, development server commands typically:

1. Validate that output directory exists and contains generated files
2. Start PHP's built-in web server: php -S localhost:PORT -t OUTPUT_DIR
3. Display access URL (e.g., http://localhost:8000)
4. Keep server running until interrupted (Ctrl+C)

Configuration Sources

The development server reads:

• OUTPUT_DIR (or PUBLIC_DIR) from container for document root
• Port number from command option or default (8000)

Sources: bin/staticforge.php76 (CONSOLE_INIT event registration)

---

site:upload Command

The site:upload command handles deployment of the generated static site to remote servers. This command is registered by a deployment feature via the CONSOLE_INIT event.

Expected Configuration

Upload commands typically use environment variables from .env:

Variable	Purpose
UPLOAD_URL	Target URL for deployment
SFTP_HOST	SFTP server hostname
SFTP_PORT	SFTP server port
SFTP_USER	SFTP username
SFTP_PASSWORD	SFTP password
SFTP_REMOTE_PATH	Remote directory path
S3_BUCKET	AWS S3 bucket name
S3_REGION	AWS S3 region

Deployment Flow

Sources: bin/staticforge.php76 (CONSOLE_INIT event registration), src/Commands/Audit/LiveCommand.php42-43 (UPLOAD_URL usage example)

---

Command Workflow Patterns

Typical Project Workflow

Command Chaining for CI/CD

Common command combinations for automated builds:

Development vs Production Builds

Aspect	Development	Production
Clean option	Optional	Recommended (--clean)
Template	Development template	Production template (--template)
Validation	Optional	Required (audit commands)
Deployment	Local only (site:devserver)	Remote (site:upload)
Drafts	Visible (SHOW_DRAFTS=true)	Hidden (SHOW_DRAFTS=false)

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php30-55 src/Commands/Audit/ConfigCommand.php1-210

---

Integration with Container and Bootstrap

All site commands receive the initialized Container instance from the bootstrap process:

Sources: bin/staticforge.php52-58

Commands access configuration and services through the container:

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php183-186 src/Commands/Audit/ConfigCommand.php38-39