The Claude API key

Nearly everything in Sgeulai runs on your Mac with nothing to set up. A handful of AI-reading commands are the exception — some work either with a key or with Apple Intelligence, two need a key specifically. This page is the whole path: why, where to get one, what it costs, where it goes, and how not to lose it.

Do you need one at all?

Command	Needs
Analyze Manuscript with AI…	Claude, or Apple Intelligence
Re-analyze, Replacing Previous AI Results…	Claude, or Apple Intelligence
Extract Facts from Article (AI) (a record's own Wikipedia section)	Claude, or Apple Intelligence
Re-analyze, Inserting New AI Results…	Claude only — no fallback
Propose Scene Splits…	Claude only — no fallback
Look Up Wikipedia References (bulk, Tools menu)	Neither — a plain Wikipedia lookup
Import Facts from Wikipedia (a record's own section)	Neither — a plain Wikipedia lookup
Continuity Check…	Neither — local rules only
Scan Manuscripts for Entity Links	Neither — local text matching
Export AI Provenance Report…	Neither — reports on AI already used, doesn't call it

Everything else — the binder, the Story Bible, wikilinks, comments, Harper, and every one of the sixteen analysis tools not listed above — never touches this at all.

Two Wikipedia features look alike and aren't. Import Facts from Wikipedia just reads the page's infobox — no AI, no key. Extract Facts from Article (AI) is a separate button that uses an engine to read the article's prose, not just its infobox — that one needs Claude or Apple Intelligence, and is hidden entirely when neither is available.

Turning AI features on

AI reading is off by default, and in a released build the Settings tab that holds the key field is hidden until it's turned on — which is normally done from inside that same tab, so the first time through needs one Terminal command instead:

defaults write com.BMI.ePub.Sgeulai showManuscriptAIAnalysis -bool YES

Quit and reopen Sgeulai afterward. Settings now has an AI tab and a Usage tab, and the toolbar's Tools menu gains its AI Analysis section. From here on, the toggle at the top of the AI tab — Read manuscripts with AI — is the normal, in-app way to turn the whole feature back off (or on again), on any Mac the project is opened on.

Getting a key

Go to platform.claude.com and sign in, or create an account.
Open Settings ▸ API Keys.
Click Create Key and give it a name — anything you'll recognize later, like "Sgeulai."
Copy the key immediately. It's shown in full exactly once, starts with sk-ant-, and Anthropic will not show it to you again — losing it before you've copied it means creating a new one.

Buying credits

A key by itself has no money behind it — creating one and adding credits are two separate steps. As of this writing, Anthropic's minimum initial purchase is $20. Add credits from platform.claude.com/settings/billing, or from inside Sgeulai: Settings ▸ Usage ▸ Claude Credits ▸ Add Credits at platform.claude.com opens the same page.

An API key can't report its own balance back to whatever's using it, so Sgeulai keeps its own running ledger instead — log what you've actually topped up on the same Usage tab, and "Estimated remaining" is computed from that, not read live from Anthropic. See Settings reference for the rest of that tab.

Putting the key into Sgeulai

Settings ▸ AI ▸ (with Read manuscripts with AI on) ▸ Claude API key. Paste it in — that's the whole step. The field's own caption states the two things worth knowing right there:

"Optional. With a key, 'Analyze Manuscript with AI' uses Anthropic's Claude for the richest extraction. Without one, it falls back to the on-device Apple Intelligence model. The key is stored in your macOS Keychain."

How not to lose it

Copy it the moment you create it. Anthropic shows the full key exactly once. A password manager is the obvious place — Sgeulai's own field is a secure, write-only box, so it never displays the key back to you either, even after you've entered it.
It lives in this Mac's Keychain, not in the project file. A .sgeulai opened on a different Mac doesn't carry the key with it — that Mac needs its own key entered in its own Settings.
To check whether one's set without seeing it, look at the "Active engine" line in Settings ▸ AI, or the Engine: … line under AI Analysis in the Tools menu.

What Sgeulai tells you before it sends anything

The first time an AI-reading run would actually put your manuscript on Anthropic's servers, Sgeulai stops and asks, rather than sending it silently:

"The text of your manuscript is sent to Anthropic's servers to be read. It leaves this Mac and travels over the internet.

This is how the AI reading works, and it is the only part of Sgeulai that sends your writing anywhere. Remove the API key in Settings → AI to use the on-device model instead, which never does.

You will not be asked again."

It only asks once per project — after that, an accepted run proceeds without asking again. Removing the key from Settings is the way back to on-device-only at any time.

If nothing is available

Trying an AI-reading command with no key and no Apple Intelligence available shows a plain alert: "No analysis engine available. Set a Claude API key in Settings, or run on a device that supports Apple Intelligence." Nothing is sent anywhere when this happens — it's a message, not a failed attempt.