CLI Automation & CI/CD

Integrate Hammer CLI into automated workflows, shell scripts, and CI/CD pipelines with JSON output and consistent exit codes.

JSON Output

Every Hammer CLI command supports --format json for machine-readable output. This makes it straightforward to parse results in scripts, CI runners, or any automation tooling.

# Get build results as JSON
hammer build --format json

# Validate content and parse the result
hammer check --strict --format json

# Inspect project configuration programmatically
hammer info --format json

# Health check with structured output
hammer doctor --format json

Output Routing

When using JSON format:

  • stdout — The final structured JSON result. Always valid JSON, safe to pipe to jq or other tools.
  • stderr — Progress messages (in verbose mode) and error output. Kept separate so stdout remains clean JSON.

JSON Conventions

  • Pretty-printed with sorted keys
  • Top-level status field with command-specific values ("success"/"failure" for build, "pass"/"fail" for check, "healthy"/"issues_found" for doctor)
  • Durations reported as durationMs (integer milliseconds)
  • Errors and warnings as arrays of objects with ruleId, message, file, and optional suggestion fields

Exit Codes

Hammer CLI uses consistent exit codes across all commands. These are compatible with set -e, CI runners, and standard shell scripting conventions:

Code Meaning When
0 Success Build succeeded, all checks passed, doctor healthy
1 Failure Build errors, check failures, doctor issues
2 Configuration error Project not found, invalid config, invalid arguments
3 Internal error Unexpected runtime error

Shell Script Patterns

Validate Then Build

Run content checks before building to catch issues early:

#!/bin/bash
set -e

# Validate content against schema
hammer check --strict
echo "Content validation passed"

# Build for production
hammer build --mode publish
echo "Build complete"

Build with Error Handling

Check exit codes for more granular error handling:

#!/bin/bash

hammer check --strict --format json > /tmp/check-result.json
exit_code=$?

if [ $exit_code -eq 0 ]; then
  echo "All checks passed, building..."
  hammer build --mode export
elif [ $exit_code -eq 1 ]; then
  echo "Content validation failed:"
  cat /tmp/check-result.json | jq '.errors'
  exit 1
elif [ $exit_code -eq 2 ]; then
  echo "Configuration error — run 'hammer doctor' to diagnose"
  exit 2
fi

Multi-Site Builds

Build several Hammer sites from a single script. Each CLI invocation is independent with no shared state:

#!/bin/bash

for site in ~/Sites/*/; do
  echo "Building $site..."
  hammer build --project "$site" --mode export --quiet
done
echo "All sites built"

Parallel Builds

Multiple hammer processes can run concurrently on different projects. There are no lockfiles or shared mutable resources:

#!/bin/bash

hammer build --project ~/Sites/site-a --mode export &
hammer build --project ~/Sites/site-b --mode export &
hammer build --project ~/Sites/site-c --mode export &
wait
echo "All sites built"

CI/CD Pipeline Integration

Hammer CLI is designed to work seamlessly in CI/CD environments. Here's how to add Hammer as a quality gate in your deployment pipeline.

GitHub Actions Example

Add Hammer CLI checks and builds to your GitHub Actions workflow:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: macos-latest
    steps:

    

  • uses: actions/checkout@v4
    • 


  • name: Install Hammer CLI run: | # Install from the Hammer CLI distribution brew install --cask hammer
    • 


  • name: Validate Content run: hammer check --strict --format json
    • 


  • name: Build Site run: hammer build --mode publish --format json
    • 


  • name: Deploy to Forge run: | # Deploy the Build/ directory to your hosting # See Forge documentation for deployment options
    •

Quality Gate Pattern

Use hammer check --strict as a quality gate that blocks deployment if content doesn't meet your schema requirements:

#!/bin/bash

set -e
# Quality gate: strict content validation
hammer check --strict --format json
# Only reached if check passed
hammer build --mode publish --format json
echo "Ready to deploy"

The --strict flag is key for CI — it promotes warnings to errors, causing the check to exit with code 1 on any issue. Without --strict, warnings like a missing slug are reported but don't fail the pipeline.

Tip: Use --format json in CI environments so you can parse and display structured error information in your pipeline logs or notifications.

Content Automation

The CLI's validation and JSON output make it a natural fit for automated content workflows where content is generated or managed programmatically.

AI Content Pipeline

Validate AI-generated content against your schema before committing:

#!/bin/bash
set -e

# AI tool generates content files into content/posts/

# Validate against schema
hammer check --strict --format json

# Build the site
hammer build --mode export

# Commit and create PR
git add .
git commit -m "Add generated content"
gh pr create --title "New content" --body "Auto-generated content, validated by Hammer CLI"

Pre-Commit Hook

Run content checks before every commit to catch issues locally:

#!/bin/bash
# .git/hooks/pre-commit

hammer check --strict --quiet
if [ $? -ne 0 ]; then
  echo "Content validation failed. Fix issues before committing."
  exit 1
fi

Next Steps