Quick Start

Get up and running with MAKI in just a few minutes.

Prerequisites

• Rust 1.80 or later (if building from source)
• OR use pre-built binaries

Step 1: Install MAKI

cargo install maki

Verify the installation:

maki --version

Step 2: Initialize a New Project

Create a new FHIR Implementation Guide project:

maki init MyIG
cd MyIG

Or initialize configuration in an existing project:

cd your-fsh-project
maki config init

Step 3: Build Your IG

Build FSH files to FHIR resources (SUSHI-compatible):

maki build --progress

This compiles FSH from input/fsh/ to FHIR JSON in fsh-generated/.

Step 4: Lint Your Files

Check your FSH files for issues:

maki lint input/fsh/

MAKI will show you any issues found:

error[correctness/duplicate-definition]: Duplicate profile definition

  > 15 │ Profile: PatientProfile
       │          ^^^^^^^^^^^^^^ Profile 'PatientProfile' is already defined
    16 │ * name 1..1 MS

  i First defined at line 8

Step 5: Format Your Code

Format your FSH files for consistent style:

maki fmt input/fsh/

The formatter will:

• Normalize spacing around : and =
• Align rules for better readability
• Preserve all comments and blank lines
• Maintain consistent indentation

You can also check formatting without modifying files:

maki fmt --check input/fsh/

Step 6: Auto-fix Issues

Many issues can be fixed automatically:

maki lint --write input/fsh/

MAKI will apply safe fixes and report what was changed.

Step 7: Convert FHIR to FSH (GoFSH)

Convert existing FHIR resources back to FSH:

maki gofsh ./fsh-generated -o ./converted-fsh --progress

Common Workflows

Build with Quality Checks

Run linter and formatter before building:

maki build --lint --format --progress

Strict Mode Build

Treat warnings as errors (useful for CI):

maki build --lint --strict

Clean Rebuild

Clean output and rebuild from scratch:

maki build --clean --progress

Next Steps

• CLI Commands Reference for all available commands
• Learn about the formatter for automatic code formatting
• Configure rules to match your project’s needs
• Learn about built-in rules to understand what MAKI checks
• Write custom rules for project-specific validation
• Integrate with CI/CD to automate linting and formatting

Common Commands

# Build FSH to FHIR
maki build --progress

# Lint with automatic fixes
maki lint --write input/fsh/

# Format FSH files
maki fmt input/fsh/

# Check formatting (useful for CI)
maki fmt --check input/fsh/

# Convert FHIR to FSH
maki gofsh ./fsh-generated -o ./output

# List all available rules
maki rules

# Get help
maki --help
maki build --help

Help and Support

• Run maki --help for command-line help
• Run maki <command> --help for command-specific help
• Check the Troubleshooting Guide for common issues