afm-cli

A Swift command-line interface tool for interacting with macOS Apple Intelligence foundation models.

Features

• Generate text using Apple Intelligence foundation models
• Multiple input methods: command-line arguments, files, or stdin (pipe)
• Streaming output option for real-time generation
• File validation to ensure compatible input
• Help and Version commands
• Comprehensive error handling for unsupported systems

Requirements

• macOS 26.0 (Tahoe) or later
• Apple Silicon Mac (M1, M2, M3, M4, M5 or later)
• Apple Intelligence enabled in System Settings
• Xcode 26.0 or later (only required for building from source)

Installation

Homebrew (Recommended)

Install using Homebrew from the custom tap:

brew tap CreevekCZ/tap
brew install afm-cli

Or install in one command:

brew install CreevekCZ/tap/afm-cli

This will:

1. Add the custom tap repository
2. Download and install the pre-built binary
3. Make it available in your PATH

To update to the latest version:

brew upgrade afm-cli

From Source

Run the install script from the project root:

./install.sh

This will:

1. Build the project in Release mode
2. Install the executable to /usr/local/bin/afm-cli (or ~/bin/ if sudo is not available)
3. Make it executable and verify the installation

Usage

Help

afm-cli --help
# or
afm-cli -h

Version

afm-cli --version
# or
afm-cli -v

Generate Text (Default Behavior)

Generate text using Apple Intelligence foundation models. The generate command is the default behavior:

# Basic usage - prompt as positional argument
afm-cli "What is Swift?"

# Explicit prompt option
afm-cli --prompt "Explain machine learning"

# From file
afm-cli --file prompt.txt

# From stdin (pipe)
echo "What is Apple Intelligence?" | afm-cli

# Multiple words as prompt
afm-cli "Write a short story about a robot learning to paint"

# With system prompt/pre-prompt to define response style
afm-cli --system-prompt "Respond in JSON format" --prompt "List 3 colors"
afm-cli -s "Write as a haiku" "Describe the ocean"
afm-cli --system-prompt "Use technical language" "Explain quantum computing"

# With conversation save/load
afm-cli -c conversation.json "Start a conversation"
afm-cli -c conversation.json "Continue our discussion"

System Prompt (Pre-Prompt)

You can optionally provide a system prompt to guide the model's response style, format, or tone:

# Define response format
afm-cli --system-prompt "Respond in JSON format" --prompt "List 3 colors"

# Define writing style
afm-cli -s "Write as a haiku" "Describe the ocean"

# Define tone/approach
afm-cli --system-prompt "Use technical language" "Explain quantum computing"
afm-cli --system-prompt "Explain like I'm 5 years old" "What is gravity?"

The system prompt is prepended to your user prompt and helps guide how the model should respond. This is useful for:

• Defining output format (JSON, XML, markdown, etc.)
• Setting writing style (poetry, technical, casual, etc.)
• Specifying tone (professional, friendly, educational, etc.)
• Providing context or constraints

Options:

• -s, --system-prompt TEXT - Provide system prompt directly
• --pre-prompt TEXT - Alias for --system-prompt

Conversation Management

Save and load conversation history using JSON files:

# Start a new conversation (creates file if it doesn't exist)
afm-cli -c conversation.json "Hello, I'm learning Swift"

# Continue the conversation (loads previous messages)
afm-cli -c conversation.json "Can you explain closures?"

# The conversation file stores the full history
cat conversation.json

How it works:

• If the file doesn't exist, a new conversation is created
• If the file exists, previous messages are loaded and included in the context
• Each exchange (user prompt + assistant response) is automatically saved
• The conversation maintains full context for multi-turn dialogues

Options:

• -c, --conversation PATH - Path to JSON file for saving/loading conversation

File Input Limitations

When using the --file option, the following restrictions apply:

• Maximum file size: 1 MB
• Encoding: UTF-8 text only
• Format: Plain text files only (binary files are rejected)
• Content validation:
  • File must not be empty
  • File must contain actual text (not just whitespace)
  • File must not contain null bytes (binary data)
  • File must contain mostly printable characters (≤5% non-printable allowed)

Examples of invalid files:

• Binary files (images, executables, etc.)
• Files larger than 1 MB
• Empty files or files with only whitespace
• Files with unsupported encodings (non-UTF-8)

Error messages will clearly indicate why a file was rejected.

Building

Using Xcode

1. Open afm-cli.xcodeproj in Xcode
2. Select the afm-cli scheme
3. Build (⌘B) or Run (⌘R)

Using Command Line

# Debug build
xcodebuild -project afm-cli.xcodeproj -scheme afm-cli -configuration Debug build

# Release build
xcodebuild -project afm-cli.xcodeproj -scheme afm-cli -configuration Release build

Error Handling

The tool provides detailed error messages for various scenarios:

System Requirements

• Framework not available: Clear message about requirements
• macOS version too old: Version check error
• Not Apple Silicon: Hardware check error
• Apple Intelligence not enabled: Runtime error with guidance
• Models not downloaded: Runtime error with troubleshooting steps

File Input Validation

• File does not exist: Clear error with file path
• File too large: Shows actual size and maximum allowed (1 MB for prompts)
• Invalid encoding: Indicates UTF-8 requirement
• Binary file detected: Identifies null bytes or excessive non-printable characters
• Empty file: Rejects files with no content or only whitespace
• File read errors: Provides specific error details

Usage Errors

• No prompt provided: Shows usage examples
• Invalid options: Clear error messages for malformed arguments

License

This project is licensed under the MIT License - see the LICENSE file for details.

Created by Jan Kožnárek on 14.11.2025.