CLI Reference

butter compile

Compiles a .butter file to a Markdown prompt (default) or other formats like JSON and YAML.

butter compile [input file] [flags]

Flags

Examples

# Basic compile — produces demo.prompt.md
butter compile demo.butter

# JSON output
butter compile demo.butter -f json

# YAML output
butter compile demo.butter -f yaml

# Custom output path
butter compile demo.butter -f json -o result.json

# Validate only (no output)
butter compile --check demo.butter

# Extract a single endpoint
butter compile api.butter --only endpoint:ProcessOrder -f json

# Exclude a block
butter compile api.butter --exclude endpoint:HealthCheck -f json

Selective Compilation

The --only and --exclude flags extract or remove specific features and endpoints. The filter syntax is block_type:name — e.g. endpoint:ProcessOrder or feature:CreateTask. Comma-separated for multiple targets.

The global context (app name, description, version) is always preserved. Both flags fail if a referenced block doesn't exist — typos are caught at compile time.

butter fmt

Formats a .butter file — normalizes indentation and spacing.

butter fmt demo.butter
butter fmt --check demo.butter   # check without modifying

Error Messages

Errors include the line number and a clear description:

Error: compilation syntax compilation error:
line 5: expected an application name after 'app'