SwiftButler

SwiftButler

Use butler to reduce Swift source into a more manageable working surface.

Setup

Install via Homebrew:

brew install cocoanetics/tap/swiftbutler

Verify:

butler --version

For local development from a checkout:

swift build
.build/debug/butler --version

Core Rules

• Prefer analyze when an agent needs API shape, not full implementation details.
• Prefer --format yaml or --format json when the result will be parsed or reused.
• Prefer check for fast validation loops before swift build.
• Use reindent to normalize indentation in place; choose exactly one of --spaces or --tabs.
• Use distribute before targeted edits when a generated file has become too large or noisy.

Fast Command Map

Analyze Swift APIs

# Default interface-style output
butler analyze Sources/MyModule

# Public API only
butler analyze Sources/MyModule --visibility public

# Recursive YAML output for tooling
butler analyze Sources --recursive --format yaml

# Write structured output to a file
butler analyze Sources --recursive --format yaml --output api.yaml

Supported formats:

• interface
• json
• yaml
• markdown

Syntax-check Swift quickly

butler check Sources --recursive
butler check Sources --recursive --json
butler check Sources --recursive --json --pretty
butler check Sources --recursive --format markdown --show-fixits

Reindent with spaces or tabs

# Default: 3 spaces
butler reindent Sources --recursive

# Explicit spaces
butler reindent Sources --recursive --spaces 2
butler reindent Sources --recursive --spaces 4

# Tabs instead of spaces
butler reindent Sources --recursive --tabs

# Preview without modifying files
butler reindent Sources --recursive --tabs --dry-run

Notes:

• --spaces accepts values from 1 to 16.
• --tabs and --spaces are mutually exclusive.
• Without --tabs, the default is --spaces 3.

Distribute large files into smaller ones

# Split one large generated file
butler distribute Generated.swift

# Preview recursive distribution
butler distribute Sources/Generated --recursive --dry-run

# Write distributed files to a separate directory
butler distribute Sources/Generated --recursive --output SplitSources

When to Use Which Command

• Use analyze to hand an LLM a compact view of types, functions, properties, and docs.
• Use check inside generation or repair loops for immediate syntax feedback.
• Use reindent after generated or patched code has inconsistent indentation.
• Use distribute when one large Swift file should become declaration-sized files that are easier to inspect and edit.