CLI Reference

Global Options

clay [options] [command]

Options:
  -V, --version     Output the version number
  -v, --verbose     Enable verbose output
  -h, --help        Display help information

Commands

init

Initialize a Clay project or generator

clay init [type] [name]

Initialize a project:

clay init

Creates a .clay file in the current directory.

Initialize a generator:

clay init generator my-generator

Creates a new generator in clay/generators/my-generator/

init-claude

Set up Claude Code hooks to prevent editing Clay-generated files

clay init-claude

Creates .claude/settings.json with a PreToolUse hook that calls clay check-generated before any Edit/Write operation. No scripts are generated — Clay handles the check entirely.

Safe to run multiple times — merges into existing settings without overwriting.

check-generated

Check if a file is Clay-generated (used internally by hooks)

echo '{"file_path": "/path/to/file.ts"}' | clay check-generated

Reads JSON from stdin, checks the .clay manifest, and exits with code 2 if the file is generated (blocking the edit). Exits 0 otherwise. This command is called automatically by the Claude Code hook — you don't need to run it manually.

init-mcp

Add the Clay MCP server to your AI platform's MCP configuration

clay init-mcp

Interactively asks which AI platforms you use, with auto-detection of platforms already present in your project (e.g. .vscode/, .claude/, .cursor/).

Supported platforms:

• VS Code / GitHub Copilot → .vscode/mcp.json
• Claude Code → .mcp.json
• Claude Desktop → system config file
• Cursor → .cursor/mcp.json

Merges into existing config files without overwriting other servers. Safe to run multiple times.

generate

Generate code from your model

clay generate <model_path> <output_path>
clay generate  # Uses .clay file

Examples:

# Explicit paths
clay generate ./clay/model.json ./src

# Using .clay file (recommended)
clay generate

# Verbose output
clay generate -v

clean

Remove all generated files

clay clean <model_path> <output_path>
clay clean  # Uses .clay file

Examples:

# Explicit paths
clay clean ./clay/model.json ./src

# Using .clay file
clay clean

watch

Watch for model changes and regenerate automatically

clay watch <model_path> <output_path>
clay watch  # Uses .clay file

Examples:

# Watch the clay directory
clay watch ./clay/model.json ./src

# Using .clay file
clay watch

Clay will monitor the model directory and regenerate when files change.

test-path

Test JSONPath expressions against your model

clay test-path <model_path> <json_path>

Examples:

# Get all types
clay test-path ./clay/model.json "$.model.types[*]"

# Get all fields
clay test-path ./clay/model.json "$.model.types[*].fields[*]"

# Filter by property
clay test-path ./clay/model.json "$.model.types[?(@.isActive)]"

# Get array-type fields
clay test-path ./clay/model.json "$.model.types[*].fields[?(@.type=='array')]"

The .clay File

The .clay file tracks generated files and stores configuration. It's created with clay init.

Structure:

{
  "model": "clay/model.json",
  "output": ".",
  "files": [
    "src/models/user.model.js",
    "src/models/order.model.js",
    "src/controllers/user.controller.js"
  ]
}

Benefits:

• Run commands without specifying paths every time
• Track which files were generated (for clean command)
• Prevent accidental modification of generated files
• Share configuration across team members

Workflow Examples

Starting a New Project

# 1. Create project directory
mkdir my-project && cd my-project

# 2. Initialize Clay
clay init

# 3. Create model directory
mkdir -p clay

# 4. Create your model
cat > clay/model.json << 'EOF'
{
  "name": "my-app",
  "generators": ["./generators/api"],
  "model": {...}
}
EOF

# 5. Generate code
clay generate

Development Workflow

# Terminal 1: Watch for changes
clay watch

# Terminal 2: Edit model and templates
vim clay/model.json
vim clay/generators/api/templates/model.js

# Files regenerate automatically!

Testing JSONPath

# Test a selector before using in generator
clay test-path ./clay/model.json "$.model.types[*]"

# Verify filtered results
clay test-path ./clay/model.json "$.model.types[?(@.isActive)]"

# Check nested paths
clay test-path ./clay/model.json "$.model.types[*].commands[*].parameters[*]"

Cleaning Up

# Remove all generated files
clay clean

# Regenerate from scratch
clay generate

Environment Variables

Clay respects these environment variables:

• NODE_ENV - Can affect formatter behavior
• DEBUG - Set to "clay:*" for debug output

Exit Codes

Tips & Tricks

• Use -v flag to see detailed output during generation
• Always test JSONPath expressions before adding to generators
• Use watch during active development for instant feedback
• Commit .clay to version control for team consistency
• Add generated files to .gitignore if they're always regenerated

alias cg="clay generate"
alias cw="clay watch"
alias cc="clay clean"