CLI Command Reference

hammer build

Runs the full Hammer build pipeline: HTML tag processing (@include, @var, @loop, @if), CSS compilation, content generation, and asset copying. Writes output to a Build/ directory by default.

This is the default subcommand — running hammer with no subcommand is equivalent to hammer build.

Options

Build Modes

Log Levels

The --quiet and --verbose flags are mutually exclusive:

• Normal (default): Build result summary — file count, errors, warnings, duration
• Verbose: Everything above plus per-file processing messages
• Quiet: Only errors, printed to stderr

Example Output

Source: /Users/me/Sites/my-blog
Output: /Users/me/Sites/my-blog/Build

✔ Build succeeded in 245ms
  42 files processed
  Build size: 1.2 MB

JSON Output

hammer build --format json

{
  "status": "success",
  "stats": {
    "filesProcessed": 42,
    "errors": 0,
    "warnings": 0,
    "durationMs": 245,
    "buildSize": "1.2 MB"
  },
  "errors": [],
  "warnings": []
}

Exit Codes

hammer check

Validates content structure and governance rules. Only meaningful for projects with Content Mode enabled (content.config.json present).

Options

What It Validates

The check command runs these validations in order:

1. Config syntax — content.config.json exists and parses without error
2. Collection directories — Each collection's content directory exists on disk
3. Template files — Referenced templates exist
4. Content parsing — Each content file (Markdown or YAML) parses successfully
5. Required fields — Front matter contains all required fields defined in your collection config
6. Slug resolution — Content files resolve a slug value from the slug field or fallback

Validation Rules

Example Output

When all checks pass:

✔ 128 files validated

When issues are found:

✖ 2 errors

[REQUIREDFIELDMISSING]
Missing required field 'summary' in collection 'posts'
  content/posts/my-post.md
  Suggestion: Add 'summary' to the front matter

[TEMPLATE_MISSING]
Template 'templates/post.html' not found for collection 'posts'
  Suggestion: Create the template file or update content.config.json

JSON Output

hammer check --strict --format json

{
  "status": "fail",
  "errors": [
    {
      "ruleId": "REQUIREDFIELDMISSING",
      "message": "Missing required field 'summary' in collection 'posts'",
      "file": "content/posts/my-post.md",
      "suggestion": "Add 'summary' to the front matter"
    }
  ],
  "warnings": [],
  "stats": {
    "filesChecked": 128,
    "durationMs": 45
  }
}

Exit Codes

hammer info

Displays project structure and configuration as seen by the CLI. Useful for debugging project setup and for automation tools to discover project topology.

Options

Information Reported

• Project name and source path
• Build output path
• Whether Content Mode is enabled
• Ignore patterns from .hammer-ignore
• Site description from .site-description
• Site URL from content.config.json
• Each collection: name, directory, format, template, output pattern, file count, and fields

Example Output

Project: my-blog
Path:    /Users/me/Sites/my-blog
Build:   /Users/me/Sites/my-blog/Build
Content: enabled

Collections:
  posts (24 files) -> content/posts
  authors (3 files) -> content/authors
URL:     https://my-blog.com

Exit Codes

hammer doctor

Runs environment and project health checks. This is the first command to reach for when setting up the CLI against a project, or when troubleshooting build issues.

Options

Checks Performed

Example Output

Hammer Doctor
─────────────
✔ Project found: /Users/me/Sites/my-blog
✔ Source directory readable: OK
✔ Build directory writable: OK (will be created on build)
✔ Content config valid: 2 collections defined
✔ Collection 'posts' directory: OK
✔ Collection 'posts' template: OK
✔ Ignore patterns: 3 patterns configured

7/7 checks passed

JSON Output

hammer doctor --format json

{
  "status": "healthy",
  "checks": [
    { "name": "Project found", "passed": true, "message": "/Users/me/Sites/my-blog" },
    { "name": "Source directory readable", "passed": true, "message": "OK" },
    { "name": "Build directory writable", "passed": true, "message": "OK (will be created on build)" },
    { "name": "Content config valid", "passed": true, "message": "2 collections defined" },
    { "name": "Collection 'posts' directory", "passed": true, "message": "OK" },
    { "name": "Collection 'posts' template", "passed": true, "message": "OK" },
    { "name": "Ignore patterns", "passed": true, "message": "3 patterns configured" }
  ]
}

The status field is "healthy" when all checks pass and "issues_found" when any check fails.

Exit Codes

Global Options

These options are available on all commands:

Next Steps

• Project Structure — How the CLI finds and configures projects
• Automation & CI/CD — JSON output, scripting patterns, and pipeline integration
• Troubleshooting — Common issues and how to resolve them