Command-Line Help for `swissarmyhammer`

This document contains the help content for the swissarmyhammer command-line program.

Installation

brew install swissarmyhammer/tap/swissarmyhammer

Command Overview:

swissarmyhammer↴
swissarmyhammer serve↴
swissarmyhammer serve http↴
swissarmyhammer init↴
swissarmyhammer deinit↴
swissarmyhammer doctor↴
swissarmyhammer completion↴
swissarmyhammer validate↴
swissarmyhammer tools↴
swissarmyhammer tools enable↴
swissarmyhammer tools disable↴
swissarmyhammer statusline↴
swissarmyhammer statusline config↴

swissarmyhammer is an MCP (Model Context Protocol) server that brings skills, workflows, and agents to AI coding tools. It supports template substitution and seamless integration with Claude Code and other ACP-compatible editors.

Global arguments can be used with any command to control output and behavior: –verbose Show detailed information and debug output –format Set output format (table, json, yaml) for commands that support it –debug Enable debug mode with comprehensive tracing –quiet Suppress all output except errors

Main commands: serve Run as MCP server (default when invoked via stdio) init Set up sah for all detected AI coding agents (skills + MCP) doctor Diagnose configuration and setup issues validate Validate configuration files for syntax and best practices completion Generate shell completion scripts

Example usage: swissarmyhammer serve # Run as MCP server swissarmyhammer init # Set up skills + MCP for detected agents swissarmyhammer doctor # Check configuration

Usage: swissarmyhammer [OPTIONS] [COMMAND]

Subcommands:

serve — Run as MCP server (default when invoked via stdio)
init — Set up sah for all detected AI coding agents (skills + MCP)
deinit — Remove sah from all detected AI coding agents (skills + MCP)
doctor — Diagnose configuration and setup issues
completion — Generate shell completion scripts
validate — Validate skills and workflows for syntax and best practices
tools — Manage tool enable/disable state
statusline — Render statusline from Claude Code JSON (stdin) or dump config

Options:

-v, --verbose — Enable verbose logging
-d, --debug — Enable debug logging
-q, --quiet — Suppress all output except errors
--format <FORMAT> — Global output format

Possible values: table, json, yaml

`swissarmyhammer serve`

Run as MCP server. This is the default mode when invoked via stdio (e.g., by Claude Code). The server will:

Expose the SwissArmyHammer tools and workflows via the MCP protocol
Watch for file changes and reload automatically

Example: swissarmyhammer serve # Stdio mode (default) swissarmyhammer serve http # HTTP mode

Or configure in Claude Code’s MCP settings

Usage: swissarmyhammer serve [COMMAND]

Subcommands:

http — Start HTTP MCP server

`swissarmyhammer serve http`

Start HTTP MCP server for web clients, debugging, and ACP agent integration. The server exposes MCP tools through HTTP endpoints and provides:

RESTful MCP protocol implementation
Health check endpoint at /health
Support for random port allocation (use port 0)
Graceful shutdown with Ctrl+C

Example: swissarmyhammer serve http –port 8080 –host 127.0.0.1 swissarmyhammer serve http –port 0 # Random port

Usage: swissarmyhammer serve http [OPTIONS]

Options:

-p, --port <PORT> — Port to bind to (use 0 for random port)

Default value: 8000
-H, --host <HOST> — Host to bind to

Default value: 127.0.0.1

`swissarmyhammer init`

Set up SwissArmyHammer for all detected AI coding agents.

This command:

Registers sah as an MCP server for all detected agents (Claude Code, Cursor, Windsurf, etc.)
Creates the .sah/ project directory
Installs builtin skills to the central .skills/ store with symlinks to each agent

The command is idempotent - safe to run multiple times.

Targets: project Write to project-level config files (default, shared with team via git) local Write to ~/.claude.json per-project config (personal, not committed) user Write to global config files (all projects)

Examples: sah init # Project-level setup (default) sah init user # Global setup for all projects sah init local # Personal setup, not committed to git

Usage: swissarmyhammer init [TARGET]

Arguments:

<TARGET> — Where to install the MCP server configuration

Default value: project

Possible values:
- project: Project-level configuration (committed to the repo)
- local: Local project configuration that is not committed
- user: User-wide (global) configuration

`swissarmyhammer deinit`

Remove SwissArmyHammer from all detected AI coding agents.

By default, only the MCP server entries are removed from agent config files. Use –remove-directory to also delete .sah/ and installed skills.

Examples: sah deinit # Remove from project settings sah deinit user # Remove from user settings sah deinit –remove-directory # Also remove .sah/ and skills

Usage: swissarmyhammer deinit [OPTIONS] [TARGET]

Arguments:

<TARGET> — Where to remove the MCP server configuration from

Default value: project

Possible values:
- project: Project-level configuration (committed to the repo)
- local: Local project configuration that is not committed
- user: User-wide (global) configuration

Options:

--remove-directory — Also remove .sah/ project directory

`swissarmyhammer doctor`

Diagnose and troubleshoot your SwissArmyHammer setup in seconds.

Save hours of debugging time with comprehensive automated checks that identify configuration issues, permission problems, and integration errors before they impact your workflow.

WHAT IT CHECKS

The doctor command runs a complete health assessment of your environment: • PATH Configuration - Verifies swissarmyhammer is accessible from your shell • Claude Code Integration - Validates MCP server configuration and connectivity • Skills - Checks directories, file permissions, and YAML syntax • File Watching - Tests file system event monitoring capabilities • System Resources - Validates required dependencies and system capabilities

WHY USE DOCTOR

• Quick Diagnosis - Complete system check in seconds, not hours • Clear Reporting - Easy-to-understand pass/fail results with actionable guidance • Early Detection - Catch configuration problems before they cause failures • Setup Validation - Verify your installation is working correctly • Integration Testing - Ensure Claude Code and MCP are properly connected

UNDERSTANDING RESULTS

Exit codes indicate the severity of findings: 0 - All checks passed - System is healthy and ready 1 - Warnings found - System works but has recommendations 2 - Errors found - Critical issues preventing proper operation

COMMON WORKFLOWS

First-time setup verification: swissarmyhammer doctor

Detailed diagnostic output: swissarmyhammer doctor –verbose

After configuration changes: swissarmyhammer doctor

CI/CD health checks: swissarmyhammer doctor && echo “System ready”

EXAMPLES

Basic health check: swissarmyhammer doctor

Detailed diagnostics with fix suggestions: swissarmyhammer doctor –verbose

Quiet mode for scripting: swissarmyhammer doctor –quiet

The doctor command gives you confidence that your development environment is properly configured and ready for AI-powered workflows.

Usage: swissarmyhammer doctor

`swissarmyhammer completion`

Generates shell completion scripts for various shells. Supports:

bash
zsh
fish
powershell

Examples:

Bash (add to ~/.bashrc or ~/.bash_profile)

sah completion bash > ~/.local/share/bash-completion/completions/sah

Zsh (add to ~/.zshrc or a file in fpath)

sah completion zsh > ~/.zfunc/_sah

Fish

sah completion fish > ~/.config/fish/completions/sah.fish

PowerShell

sah completion powershell >> $PROFILE

Usage: swissarmyhammer completion <SHELL>

Arguments:

<SHELL> — Shell to generate completion for

Possible values: bash, elvish, fish, powershell, zsh

`swissarmyhammer validate`

Catch configuration errors before they cause failures with comprehensive validation.

The validate command ensures quality and correctness across your entire SwissArmyHammer configuration, detecting syntax errors, structural issues, and best practice violations before they impact your workflows.

Quality Assurance

Comprehensive Validation: • Skill files from all sources (builtin, user, project) • Workflow definitions from standard locations • MCP tool schemas and CLI integration (with –validate-tools) • Template syntax and variable usage • YAML frontmatter structure • Required field presence and format • Best practice compliance

Early Error Detection: • Find syntax errors before execution • Identify missing required fields • Detect template variable mismatches • Validate workflow state machine structure • Check MCP tool schema correctness • Verify CLI integration compatibility

CI/CD Integration: • Automated quality checks in build pipelines • Exit codes indicate validation results • Quiet mode for clean CI output • JSON output for tool integration • Fast execution for rapid feedback

What Gets Validated

Skill Files: • YAML frontmatter syntax correctness • Required fields: title, description • Template variable declarations match usage • Liquid template syntax validity • Parameter definitions and types • Default value correctness • Partial marker handling

Workflow Files: • State machine structure integrity • State connectivity and transitions • Action and tool references • Variable declarations and usage • Conditional logic syntax • Loop and iteration constructs • Error handling configuration

MCP Tools (with –validate-tools): • JSON schema correctness • Parameter type definitions • Required vs optional field specifications • Tool description completeness • CLI integration requirements • Documentation quality • Best practice adherence

Validation Modes

Standard validation (skills and workflows):

sah validate

Comprehensive validation (including MCP tools):

sah validate --validate-tools

CI/CD mode (errors only, no warnings):

sah validate --quiet
sah validate --validate-tools --quiet

Machine-readable output:

sah validate --format json
sah validate --validate-tools --format json

Exit Codes

0 - All validation passed, no errors or warnings
1 - Warnings found but no errors
2 - Errors found that require fixes

Use exit codes in scripts and CI pipelines:

sah validate || exit 1

Discovery and Sources

Skills validated from: • Built-in skills (embedded in binary) • User skills ($XDG_DATA_HOME/sah/skills) • Project skills (./.skills/)

Workflows validated from: • Built-in workflows (embedded in binary) • User workflows (~/.sah/workflows/) • Project workflows (./workflows/)

MCP tools validated from: • SwissArmyHammer tool definitions • CLI command integration points • Tool parameter schemas

Common Use Cases

Pre-commit validation:

sah validate --quiet && git commit

CI pipeline check:

sah validate --validate-tools --format json > validation-report.json

Development workflow validation:

sah validate --verbose

Quality gate in deployment:

sah validate --validate-tools --quiet || exit 1

Validation Checks

YAML Frontmatter: • Syntax correctness • Required fields present • Field types match expectations • Valid enum values

Template Syntax: • Liquid template parsing • Variable references exist • Filter syntax correctness • Control flow validity • Partial references resolve

Workflow Structure: • All states are reachable • Transitions are valid • Actions reference existing tools • Variables are declared before use • Error handlers are properly configured

MCP Tool Schemas: • JSON schema validity • Parameter type correctness • Required field specification • Tool description quality • CLI integration completeness

Best Practices: • Descriptive titles and descriptions • Proper parameter documentation • Sensible default values • Clear error messages • Consistent naming conventions

Examples

Basic validation:

sah validate

Full system validation:

sah validate --validate-tools

Quiet mode for CI:

sah validate --quiet

Detailed output:

sah --verbose validate

JSON output for tooling:

sah validate --format json | jq '.errors'

Validate after changes:

sah validate --validate-tools --verbose

Output Formats

Table format (default): • Human-readable tabular output • Color-coded error/warning levels • File paths and line numbers • Clear error descriptions

JSON format: • Machine-parseable structured output • Complete error and warning details • Suitable for CI integration • Easy tool consumption

YAML format: • Human-readable structured output • Hierarchical error organization • Good for documentation • Easy diff comparison

Troubleshooting

Validation errors in skills: • Check YAML frontmatter syntax • Verify all required fields present • Ensure template variables declared • Test Liquid template syntax

Validation errors in workflows: • Verify state machine structure • Check all state transitions • Ensure action references valid • Validate variable declarations

Validation errors in tools: • Review JSON schema correctness • Check parameter type definitions • Verify required fields specified • Ensure documentation complete

Integration with Development Workflow

Pre-commit hook:

#!/bin/bash
sah validate --quiet || {
  echo "Validation failed. Fix errors before committing."
  exit 1
}

Git hook (.git/hooks/pre-commit):

#!/bin/bash
sah validate --validate-tools --quiet

Make target:

validate:
	sah validate --validate-tools --quiet

.PHONY: validate

CI pipeline (GitHub Actions):

- name: Validate Configuration
  run: sah validate --validate-tools --format json

Benefits

Catch Errors Early: • Find problems before runtime • Prevent workflow failures • Avoid wasted execution time • Reduce debugging effort

Ensure Quality: • Enforce best practices • Maintain consistent standards • Improve documentation quality • Promote good patterns

Enable Confidence: • Deploy with certainty • Refactor safely • Share configuration reliably • Integrate automatically

Support Automation: • CI/CD quality gates • Automated testing • Pre-commit validation • Continuous quality monitoring

The validate command is your quality assurance system for SwissArmyHammer configuration, ensuring that skills, workflows, and tools are correct, complete, and ready for reliable operation.

Usage: swissarmyhammer validate [OPTIONS]

Options:

-q, --quiet — Suppress all output except errors. In quiet mode, warnings are hidden from both output and summary
--format <FORMAT> — Output format

Default value: table

Possible values: table, json, yaml
--validate-tools — Validate MCP tool schemas for CLI compatibility

`swissarmyhammer tools`

Manage which MCP tools are enabled or disabled.

Tools are enabled by default. Disable tools you don’t need to reduce the tool surface visible to AI agents.

Examples: sah tools # List all tools with status sah tools disable # Disable all tools sah tools enable shell git # Enable specific tools sah tools disable kanban web # Disable specific tools sah tools enable # Enable all tools sah tools –global disable web # Disable web globally

Usage: swissarmyhammer tools [OPTIONS] [COMMAND]