CLI Troubleshooting

Diagnose and resolve common issues with Hammer CLI using the doctor command, exit codes, and error messages.

Start with hammer doctor

When something isn't working as expected, hammer doctor is the first command to run. It checks your project environment and reports the status of each component:

hammer doctor
Hammer Doctor
─────────────
✔ Project found: /Users/me/Sites/my-site
✔ 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

Any failed check is marked with ✖ and includes a message explaining what's wrong. Fix the reported issue, then run hammer doctor again to confirm the fix.

Tip: Use hammer doctor --format json to get structured results you can inspect programmatically or share with others when seeking help.

Common Issues

Command not found: hammer

The CLI isn't installed or isn't on your PATH.

  • If you installed from the Hammer app, try quitting and reopening your terminal to reload your PATH
  • Verify the installation: run which hammer to check if it's on your PATH
  • Reinstall via Hammer → Settings → Install CLI or use the standalone installer

Project not found (exit code 2)

The CLI couldn't locate a Hammer project at the given path or in parent directories.

  • Verify you're in the right directory: run pwd and check your project path
  • If using --project, confirm the path exists and is spelled correctly
  • Run hammer info to see what the CLI detects in the current directory

Build directory not writable

The CLI can't create or write to the Build/ directory.

  • Check file permissions on the project directory
  • If you're using a custom --output path, make sure the parent directory exists and is writable
  • On macOS, check that terminal has the required disk access permissions in System Settings

Content config invalid (CONFIG_INVALID)

Your content.config.json has a syntax error or doesn't match the expected schema.

  • Validate the JSON syntax — look for trailing commas, missing quotes, or unmatched brackets
  • Check that collection paths, templates, and field types are correct
  • Compare with the configuration reference

Missing required fields (REQUIREDFIELDMISSING)

One or more content files are missing fields marked as required in your collection config.

  • Run hammer check to see which files and fields are affected
  • Add the missing fields to the front matter of each reported file
  • If a field shouldn't be required, update content.config.json to set "required": false

Template not found (TEMPLATE_MISSING)

A collection references a template file that doesn't exist on disk.

  • Check the template path in content.config.json for typos
  • Verify the template file exists at the specified path relative to the project root
  • Create the missing template or update the config to point to the correct file

Collection directory missing (COLLECTIONDIRMISSING)

A collection defined in content.config.json references a directory that doesn't exist.

  • Create the missing directory (e.g., mkdir -p content/posts)
  • Or update the path in your collection config to point to the correct directory

Content file parse errors (PARSE_ERROR)

A Markdown or YAML content file couldn't be parsed.

  • Check the front matter in the reported file — YAML front matter must be enclosed between --- delimiters
  • Verify YAML syntax: proper indentation, no tabs mixed with spaces, quoted strings where needed
  • For YAML-only collections, ensure the entire file is valid YAML

Understanding Exit Codes

Exit codes help you quickly identify the category of issue:

Code Meaning Action
0 Success Everything is fine
1 Failure Check the error output for specific issues in your content or build
2 Configuration error Run hammer doctor to diagnose project or config problems
3 Internal error Unexpected issue — try again, and contact support if it persists

You can check the exit code of the last command in your terminal with:

hammer build
echo $?

Diagnostic Workflow

When encountering issues, follow this sequence:

  1. Run hammer doctor to check the project environment
  2. Run hammer info to verify the CLI is seeing the correct project and configuration
  3. Run hammer check to validate content structure
  4. Run hammer build --verbose to see per-file processing output and identify where the build fails

For automation or sharing diagnostics, use JSON output to capture structured results:

# Full diagnostic dump
hammer doctor --format json > doctor.json
hammer info --format json > info.json
hammer check --format json > check.json

Reading Terminal Output

In human-readable output, Hammer uses these symbols:

Symbol Meaning
✔ Success / passed
✖ Failure / error
⚠ Warning

Errors are printed to stderr, so they're visible even when piping stdout to a file or another command.

Next Steps