A lightweight Go SDK for Apple's fm command-line tool.
Install · Quick start · Examples · Compatibility · Development
apple-fm-go brings Apple's fm CLI into Go applications: send prompts, attach images, request structured JSON, and propagate cancellation through the subprocess. The package uses only the Go standard library, with no CGo, Swift, or Python build dependency.
Experimental beta: v0.1.0-beta.1. The Go wrapper is tested with fake subprocesses; its CLI contract still needs verification against a real macOS 27 installation before v0.1.0. The compatibility review records the evidence and remaining checks. This is an independent project, not affiliated with or endorsed by Apple.
- Text and image prompts — instructions, model selection, and image paths in one request.
- Structured output — schema generation and JSON replies, with raw output retained on parse errors.
- Context cancellation — deadlines and cancellation reach every subprocess operation.
- Inspectable errors — match categories with
errors.Isand inspect exit status, stdout, and stderr. - Portable imports — compile the SDK and examples for Linux, macOS, and Windows on amd64 and arm64; inference requires Apple's executable.
Responses are buffered until the process exits. Streaming, persistent conversations, and tool calling are not exposed by this SDK.
| Requirement | Details |
|---|---|
| Build | Go 1.24 or later |
| Inference | macOS 27 on an Apple Intelligence-capable Mac with the model available |
| Executable | fm on PATH, or an explicit executable path passed to fm.New |
| Setup | Follow the installed CLI's setup and license instructions; the SDK never runs sudo or accepts terms |
Apple introduced the CLI in WWDC26 session 334. Apple's separate Python SDK supports macOS 26.0+ with Xcode 26.0+ and Python 3.10+; those requirements do not apply to this CLI wrapper.
On a host without fm, the Go package still compiles and calls return fm.ErrNotFound. This allows applications to offer the provider conditionally.
Install the beta from the public Go module:
go get github.com/Obedience-Corp/apple-fm-go@v0.1.0-beta.1Pin the explicit beta version while the API and CLI mapping are provisional. See the release notes and changelog. For release maintenance, see Releasing apple-fm-go.
Send one prompt with a deadline:
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/Obedience-Corp/apple-fm-go/pkg/fm"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := fm.New("") // Locate fm on PATH.
response, err := client.Respond(ctx, "What does chmod do?", &fm.RespondOptions{
Instructions: "Answer in one sentence.",
})
if err != nil {
log.Fatal(err)
}
fmt.Print(response.Stdout)
}Use fm.New("/path/to/fm") to choose an executable. Leave Client.Env nil to inherit the parent environment, or set it to supply the child's environment explicitly.
Every operation accepts a context.Context. Cancellation kills the process group on Unix, including helpers started by fm; on Windows it kills the direct subprocess.
Run these programs from a checkout with a real fm installation:
| Example | Demonstrates | Command |
|---|---|---|
| Text response | A prompt with instructions and interrupt handling | go run ./examples/respond "What does chmod do?" |
| Structured output | Generate a schema, request JSON, and decode into a Go struct | go run ./examples/schema |
| Image prompt | Attach an image to a prompt | go run ./examples/image Screenshot.png |
These are runnable examples, not recorded native verification. The schema example also exercises provisional --text and integer-field flags; see compatibility.
| Method | Result |
|---|---|
client.Available(ctx) |
Readiness and raw availability output |
client.Respond(ctx, prompt, opts) |
Buffered stdout, stderr, and optional JSON |
client.CountTokens(ctx, request) |
Parsed token count |
client.SchemaObject(ctx, schema) |
Schema JSON to write to a file and use with SchemaPath |
Browse package source or run go doc ./pkg/fm in a checkout for the exported API.
| Field | Behavior |
|---|---|
Instructions |
Instruction text for the model. |
Model |
Leave empty for the CLI default. Apple documents pcc for Private Cloud Compute (subject to usage limits). Values pass through unchanged; system has not been confirmed as an explicit CLI model name. |
ImagePaths |
One image flag per path, in order. |
SchemaPath |
An existing schema file. The reply must be JSON and is returned in Response.JSON. Use SchemaObject to produce the file. |
Text |
A document passed with the text flag instead of a positional prompt. When Text is set, pass an empty prompt and put the task in Instructions. |
Subprocess failures return an *fm.Error with the subcommand, exit code, stdout, and stderr. Local argument validation may return other errors. Cancellation remains discoverable through errors.Is(err, context.Canceled) or context.DeadlineExceeded. Match subprocess categories with errors.Is:
| Error | Meaning |
|---|---|
ErrNotFound |
fm is not on PATH or Client.Bin does not exist |
ErrLicense |
the fm terms are not accepted |
ErrUnavailable |
the model is not downloaded, or Apple Intelligence is off |
ErrContextWindow |
the prompt does not fit |
ErrGuardrail |
the model refused the prompt |
ErrUnknownModel |
fm rejected the model name |
ErrSchema |
fm rejected the schema, or a field cannot be expressed as flags |
ErrSchemaOutput |
the reply or schema was not JSON |
ErrTokenCount |
fm count-tokens did not print one integer |
Until exit codes from macOS 27 are captured, categories are best-effort matches against assumed stderr prefixes, not an Apple error-code contract. Unknown failures remain unclassified; the full stderr is always kept on the error.
Reviewed against Apple's published documentation on 2026-10-29. This SDK wraps CLI operations; it does not expose the complete Foundation Models framework.
Apple's Foundation Models updates describe image analysis, Dynamic Profiles, tool-calling controls, model APIs, and revised Swift error types. Those APIs do not establish equivalent CLI flags or exit codes. Availability, token counting, some flag forms, and error categories still await native verification.
See the compatibility review for the source audit, unsupported capabilities, and commands to verify before a release.
| Go | fm arguments |
|---|---|
Available |
available |
Respond |
respond [--instructions=…] [--model=…] [--image=…]… [--schema=…] (--text=… | -- <prompt>) |
CountTokens |
count-tokens --text=… |
SchemaObject |
schema object --name=… --string=… --int=… [--array] |
Flag names live in pkg/fm/flags.go; argument ordering and output parsing live in the corresponding operation files. The compatibility review separates Apple-documented spellings from assumptions. In particular, available, count-tokens, --text, --int, and error prefixes still require native confirmation.
Use Just for the repository's checks:
just --list # Discover available commands
just test # Isolated fake-process tests with the race detector
just lint # Formatting, vet for both tags, optional golangci-lint
just check cross-build # Linux/macOS/Windows × amd64/arm64, without CGo
just test-applefm # Native smoke tests; unavailable prerequisites skip
just check native-required # Native release gate; missing prerequisites failThe unit suite runs in a disposable Docker container with read-only source and networking disabled. Docker and the golang:1.24-bookworm image are required. Checks live in the modular .justfiles/check.just; CI uses the same recipes.
Native tests check availability, a nonempty on-device response, schema JSON, and token counts with bounded contexts. A skipped run does not establish compatibility. Image/PCC behavior and schema round-trips require separate native verification.
For CLI compatibility fixes, include the macOS version, relevant fm --help output, and a minimal reproduction with private inputs removed. Update the compatibility review, add a regression test for changed behavior, and run the checks above. Keep new APIs grounded in observed CLI behavior.
- obey-go-sdk — Go client for the Obey daemon.
- claude-code-go — Claude Code CLI SDK.
- muse-spark-go — Muse CLI and Session Protocol SDK.
Apache-2.0. See LICENSE.