This page describes Calíope 1.5, the version we are building right now. 1.4 is finished and in App Review, and the store serves 1.3 on the Mac and 1.2 on iPad. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Calíope speaks the language you give it in System Settings.
Where it is: Calíope › Preferences › General
Calíope is translated into five languages: English, Spanish, French, German and Italian. With the system in any other one, it shows English.
You choose the language in the system settings, not inside the app, and you choose it per app: your device can be in one language and Calíope in another.
- On iPad and iPhone: Settings › Calíope › Preferred Language.
- On the Mac: System Settings › General › Language & Region › Applications.
In Preferences › General you can see which language it is in, and a button that takes you there.
The change also reaches the widget and the Siri shortcuts, which used to stay in the device language.
Up to the previous version there was a picker inside the app. It was removed: it duplicated a setting the system already has, and what you picked in there was ignored by the Siri phrases and by the permission prompts, so the app could end up speaking two languages at once.
Language, query log, error log, biometrics, and usage tips.
Where it is: Calíope › Preferences › General
The General tab contains the following sections:
Language: it says which language Calíope is in and takes you to the system setting where it changes. There is no picker inside the app: the language is chosen per application in System Settings › General › Language & Region › Applications, and on iPad and iPhone in Settings › Calíope › Preferred Language. See the Interface Language topic for more details.
Logging: enable or disable the successful query log and the query error log. The log is stored in UserDefaults and can be viewed from the Query Log tab of the workspace.
Usage tips: the Show usage tips on launch toggle controls whether TipKit displays contextual help bubbles the first time you use each feature of the application. Disable it if you prefer an interface without pop-up tutorials.
Biometrics: the Require Face ID or Require Touch ID toggle asks for biometric authentication before connecting to any server. It is on this very tab, on macOS and on iPad, and it only appears if the device has biometrics available.
Keywords: general, preferences, log, logging, language, biometrics, face id, touch id
Lets scheduled backups and monitoring stay active when you close the window, macOS only.
Where it is: Calíope › Preferences › General
By default Calíope quits entirely when you close the last window. If you have scheduled backups or server monitoring enabled, that termination interrupts those background tasks.
Open Preferences › General › Window close behavior and enable Keep Calíope running in the background. With the option enabled:
- The Dock icon disappears when you close the window — Calíope stops being a "regular" app and becomes an accessory.
- The menu bar icon (top-right of the screen) stays visible and from there you can:
- Open window — reopens the UI in the current process, preserving sessions, connections, and the scheduler.
- New instance — opens a completely independent Calíope process.
- Quit — actually terminate the app.
- The backup scheduler, the monitoring engine, and the widget refresher keep running.
To return to the default behavior, turn the switch off: if you disable it while the window is hidden, Calíope immediately returns to regular mode and reappears in the Dock.
This preference applies only on macOS. On iPad the operating system manages the lifecycle on its own.
Keywords: background, menu bar, dock, scheduled backup, scheduler, monitoring, run always, hide window, accessory
Launches Calíope automatically when you log into your account, ideal for scheduled backups.
Where it is: Calíope › Preferences › General
Enable this preference if you want Calíope to start automatically every time you log into your macOS account, without having to open it manually.
How it works. Calíope registers itself as a system Login Item. The first time you enable the option, macOS may ask for explicit approval: you'll see a system prompt or System Settings › General › Login Items will open with Calíope listed. Confirm there and it stays enabled.
When it's useful.
- Scheduled backups. If you rely on the scheduler for daily or weekly backups, combining this with Keep Calíope running in the background gives you the complete flow: at login Calíope starts; when you close the window it stays in the menu bar; backups fire on schedule without you having to open anything.
- Server monitoring. If you left monitoring active in Dashboard tabs, snapshots keep accumulating from the first minute of the session.
How to manage it from the system. At any time you can open System Settings › General › Login Items and disable Calíope from there — the Preferences toggle reflects that change the next time you open Preferences.
If enabling fails. An orange message will appear below the toggle with the reason. The most common cause is macOS having Calíope blocked in Login Items (from a previous manual disable). Open System Settings, allow Calíope, and retry.
This preference applies only on macOS. On iPad the Login Items concept doesn't exist.
Keywords: login, startup, autostart, automatic, scheduled backup, scheduler, login items, open at login, launch at startup
Font, tab size, auto-completion, and SQL editor options.
Where it is: Calíope › Preferences › Text editor
Text:
- Editor font size (10–26 pt) — controls the text size in the SQL editor writing area.
- Tab size (2–30 spaces) — number of spaces inserted by the Tab key when indenting SQL code.
Features:
- Auto-indentation — when pressing Enter in the editor, the new line is indented to the same level as the previous one. Useful for writing BEGIN…END blocks or nested subqueries.
- Autocomplete SQL keywords — displays MySQL/MariaDB keyword suggestions as you type. Can be enabled/disabled without restarting the app.
- Uppercase SQL keywords on format — when using Beautify, SELECT, FROM, WHERE, etc. are written in uppercase.
- Show line numbers — displays the number of each line in the left margin of the editor, useful for referencing errors.
- Trim trailing whitespace — automatically removes trailing whitespace at the end of each line before executing or saving the editor content.
Results table font size:
The SQL Editor's results toolbar has its own size control, next to the word table: two buttons with the number between them, from 11 to 26 points. It is independent of the editor size, and it can also be changed by pinching with two fingers over the grid —trackpad on macOS, two fingers on iPad—. The value is saved between sessions.
Keywords: editor, font, font size, tab size, autocomplete, line numbers, indentation, results, font zoom, trailing spaces, uppercase, keywords
Group, sort, move and delete the saved connection profiles.
Where it is: Calíope › Preferences › Connections
The Connections tab is available on macOS and on iPad, and it is the inventory of every saved profile.
They are grouped by their group, with the group name and how many connections it holds in each header; the ones that belong to none fall under No group, at the end. Within each group they are sorted alphabetically by name.
Changing the order. On macOS, by clicking any column header: name, type, user, server, port, database or collation. On iPad, with the Sort by control in the footer, which offers name, server, user and type. Groups do not move: the order you choose is the one inside each of them.
What you can do to a connection. Right-click on macOS, touch and hold on iPad: test the connection, move it to another group — or out of all of them — and delete it. On iPad you can also delete it by swiping the row to the left. Deleting asks first and names the connection, because it takes with it the saved password, the query history and any SQL it had stored, and there is no undo.
To edit a profile's data — host, credentials, SSL, SSH tunnel — go back to the Connection Manager, the home screen before connecting, and select it in the sidebar. This tab does not edit: it manages.
Import / Export profiles: the footer includes buttons to export every profile to a JSON file and to import from a previously exported one. Useful for migrating settings between machines or for keeping a copy. The export does not include passwords — they live in the Keychain — nor the contents of certificates and keys, only their paths.
Configure the provider, API keys, and response length globally.
Where it is: Calíope › Preferences › AI Assistant
Choose the provider and fill in what that provider needs: cloud ones ask for your API key; Apple Intelligence asks for nothing, because the model runs on the device; Ollama asks for the address where it listens, and no key at all. Where a model is chosen, the reload button lists what that provider publishes: in the cloud, the ones on your account; in Ollama, the ones you have downloaded.
The Generation section holds the Send schema to the model switch and the Maximum SQL length picker, which sets how many tokens the model may generate per answer. See the Maximum length of generated SQL topic for when to use each option.
If the provider asks for a key and you do not have one yet, the assistant runs in demo mode with sample answers. What you save here applies to the AI Assistant in every tab and on all three platforms (macOS, iPad and iPhone).
Keywords: AI, OpenAI, Gemini, Claude, Apple Intelligence, Ollama, API key, model, GPT, configure assistant, tokens, maximum length, generation, no key, local
How the help bubbles are handed out: one each time you enter a tool, never two at once.
Where it is: Calíope › Preferences › General
Calíope ships over seventy usage tips: short bubbles anchored to the control they talk about, for features you can't work out just by looking.
They're handed out one at a time
Every tool has its own ordered list. On entering you'll see at most one tip, and the next visit brings the next one. The SQL Editor, for instance, has twenty-three: you'll meet them across twenty-three visits, never all at once.
They're ordered by what saves you most
The ones that prevent a mistake come first — the search/replace mismatch, safe mode — and the conveniences come later. If you stop using a tool early, you'll still have seen the ones that mattered.
A tip is spent when it's shown
It's marked as seen when it appears, not when you dismiss it: enter and leave straight away and that tip won't come back. This is deliberate — we'd rather not repeat anything to anyone — and it's what the replay button is for.
Turning them on, off, and again
- Settings › General › Tips governs both: the switch turns them off immediately, and Show the tips again restores them from the first one.
- The reset is applied by the app at launch, so you'll need to quit and reopen it. The screen says so while it's pending.
On iPhone they're separate
The iPhone runs Calíope itself, so its tips are the same tips and its switch is the same switch — one per device, like every other preference of this kind.
They block nothing
A tap or a click outside the bubble dismisses them, and they never ask for confirmation.
Keywords: tips, bubbles, contextual help, tooltip, onboarding, first run, tutorial, reset tips, show tips, replay, tipkit
What Calíope can notify you about, when permission is requested, and why a notice never repeats.
Where it is: Calíope › Preferences › Notifications
Calíope can tell you what happened while you were looking at something else. Every notice is a local notification: the app produces it on your device and it goes through no server.
What it notifies
• Long query completed: when a query passes the threshold you set (5 s by default).
• SSH tunnel: when the tunnel drops, and when it comes back.
• Manual backup: on finish and on failure. These two are the only ones silenced while Calíope is in front of you.
• iCloud sync: when it fails. Only shown with iCloud enabled.
• Row volume: when a result passes the row count you set.
Permission is requested when you turn a switch on, not at launch: until you say you want a notice, Calíope asks the system nothing. If they are denied in System Settings, this section says so at the top and takes you there — with permission denied none arrive, however many switches are on.
A notice never repeats. Each kind has a one-minute cooldown; the iCloud one, fifteen. A tunnel that drops and returns thirty times in a minute notifies once.
What is notified is recorded. With system messages enabled, each notice also leaves a message in the inbox the iPhone and the watch read — behind the same switch and within the same cooldown: without that, one notice would leave thirty rows on your wrist. The two manual-backup ones are the exception, because the run history already emits their message and it would show up twice.
The Test button sends a sample notification, so you can see how the system presents it.
Calíope remembers which tabs you had open per server and brings them back when you reconnect to that server.
Where it is: Calíope › Preferences › Restore tabs
When you quit Calíope, the app writes a local snapshot with your open tabs, indexed by connection profile. On the next run, when you manually reconnect to a saved profile, its tabs come back automatically.
Calíope never auto-reopens connections at launch. This is deliberate for both security and UX:
- Silently reopening authenticated sessions without prompting for the password would be unsafe.
- Chaining password prompts for several sessions at startup is a bad experience.
- A downed server would stall the app's launch.
So the flow is explicit: at launch you see the Connection Manager; when you pick a profile and connect, if there were saved tabs for that profile they appear in the workspace.
Preferences › Restore tabs lets you choose:
- Reopen my previous tabs (default) — restore tabs when reconnecting to the same server.
- Start fresh — discard the snapshot and always start with a blank editor tab.
What is and isn't restored:
- ✅ Per-profile tabs (SQL Editor, Dashboard, Catalogs, ER Diagram, Backup, …) come back with their title and initial payload.
- ✅ The SQL you had typed in each editor is already preserved separately (editor_state.json).
- ✅ Offline editor tabs — restored eagerly at launch (they don't require authentication).
- ❌ MySQL connections / SSH tunnels — never auto-reopened.
- ❌ Live query results, in-flight backup/migration/maintenance progress — transient state, not worth reviving halfway.
Storage: the snapshot lives at ~/Library/Application Support/Caliope/session_restore.json. It is per-device — not synced through iCloud — because a Mac's ideal open-tab set (many tools at once) usually differs from an iPad's (one task at a time).
Keep connections, snippets, history, and preferences synced across all your Apple devices.
Where it is: Calíope › Preferences › General
Calíope can sync your data between macOS, iPad and iPhone via iCloud, eliminating the need to configure each device manually.
What gets synced:
- Connection profiles (connections.json) — all your saved servers.
- Editor state (editor_state.json) — the last SQL you had open.
- Safe mode (editor_safemode.json) — the state of the safe mode toggle.
- Preferences — font size, editor options, AI configuration.
- SQL snippets — your saved code snippet collection.
- Query history — the last 100 entries per server (due to iCloud KV Store limits).
- ER layouts — saved node positions in ER diagrams.
- Passwords — credentials are automatically migrated between the local Keychain and iCloud Keychain.
How to enable sync:
1. Make sure iCloud is active and you are signed in to your Apple ID in System Settings › Apple ID.
2. Open Preferences › General › iCloud.
3. Enable the Sync Calíope with iCloud toggle.
4. Confirm by pressing Enable and migrate data in the dialog.
5. Local data is copied to iCloud and sync is activated.
How to disable sync:
1. Open Preferences › General › iCloud.
2. Disable the toggle.
3. Confirm by pressing Disable in the dialog.
4. Data is copied back to local storage. The iCloud copy is not deleted.
If iCloud is unavailable:
When the device has no active iCloud session, the toggle appears disabled with the message \"iCloud not available. Sign in at System Settings → Apple ID.\"
Sync limits:
iCloud KV Store has a 1 MB limit. Calíope truncates query history to the 100 most recent entries per server before syncing to stay within the limit. If usage exceeds 80% of the limit, a warning is logged in the local diagnostics.
Privacy and queries — important notice:
The synced query history may contain sensitive information: passwords embedded in SQL, personal data (names, emails, IDs), financial data, or other confidential content. Before enabling iCloud sync, review your history to make sure it does not include this type of data. Calíope displays this warning in the activation dialog and in the iCloud section of Preferences while sync is active. To clear your history, use Preferences › General › Delete My Data.
Stops the computer from sleeping from inactivity while you have a long job running.
Where it is: Workspace › Keep Awake
The cup button in the toolbar keeps your Mac awake. It is useful when a backup, an import or a long query needs to finish and you are going to step away from the keyboard.
It is manual and indefinite: it does not expire by time and it does not switch itself on for any task. You turn it on, and it stays on until you turn it off or quit Calíope. It is never restored on the next launch, precisely so that nobody ends the week with a laptop that has been awake for days.
There are two levels. By default the system stays awake but the display is free to turn off: that uses less battery and generates less heat. In Settings › General you can also keep the display on, which you only need if you are going to keep watching the screen. Changing that preference while the mode is on applies immediately.
While it is on, the status bar at the bottom of the window shows an indicator, so it is never on without you being able to see it. You can also toggle it from Window › Keep Awake, or with Control-Option-C.
To verify it yourself, run "pmset -g assertions" in Terminal: the assertion appears with Calíope's name.
On iPad the scope is different: it keeps the screen on, and only while Calíope is in the foreground. iPadOS does not offer a way to keep the system awake separately from the screen.
Closing the lid is a hardware sleep, and no app can prevent it.
Where it is: Workspace › Keep Awake
"Keep Awake" blocks idle sleep, which is the one that happens when you stop using the computer. Closing the lid is a different thing: it is a sleep forced by hardware, and no application can prevent it — not Calíope, and not the "caffeinate" command in Terminal either.
The only way to keep working with the lid closed is clamshell mode, which requires the Mac to be plugged in and connected to an external display plus an external keyboard or mouse. In that setup the Mac stays awake on its own and you do not need "Keep Awake" at all.
Two other limits worth knowing: an assertion does not wake a machine that is already asleep, it only prevents it from falling asleep; and it does not block a manual sleep from the Apple menu.
A single place to see everything Caliope has in flight, even if you are on another tab, another server or another app.
Where it is: Workspace › Activity
Status appears in three places, each answering a different question:
· A dot next to a tab’s name when that tab is working, and next to the server picker when the work is on another connection. This is what solves running a query and then moving elsewhere.
· The sidebar footer, where CPU and memory usage already lived, opens the full detail: what is running, on which server, for how long, with progress when it is known, plus active modes and recently finished operations.
· An indicator in the toolbar, next to the “Keep Awake” button, with the number of running operations. It exists because the sidebar can be hidden. It opens the same panel.
The bottom status bar still reports the tab in front of you; it only adds a notice when there is work outside the current view.
When the app is in the background, completion is reported by a system notification. You configure that in Settings › Notifications.
Tasks and modes are different things, and instant operations are not announced.
Tasks start and finish: queries and statement batches, manual and scheduled backups, restores, data migrations, table maintenance, imports, AI assistant requests, iCloud sync and the widget refresh. They carry elapsed time and, when it is known, progress.
Modes are on until someone turns them off: “Keep Awake”, server monitoring, having scheduled backups, and open SSH tunnels. They never finish, so they carry neither a bar nor a stopwatch; they live in their own section and do not count towards the indicator’s number.
What does not show up: anything shorter than a second. Loading the schema tree, opening a diagram or listing columns is instant in the normal case, and announcing it would be a flicker that teaches you to ignore the indicator.
If an operation has no progress it is because the server does not say how much is left. In that case you get elapsed time: a bar that fills on its own would be a fabrication.
Keywords: tasks, modes, threshold, progress, noise, what appears
Each entry in the panel offers only what it can actually do.
Go to activates the session and the tab where the task lives. A scheduled backup has no tab — it fires on its own, with nobody opening anything — so the panel says there is no destination instead of leaving a button that goes nowhere.
Stop only appears when the operation can genuinely be stopped:
· A query is cut with KILL QUERY on its own connection, which does not require the PROCESS privilege. If that message cannot be sent, you are told: the query may still be alive on the server.
· Manual backups, restores, migrations and table maintenance stop from the panel or from their own tool.
· Scheduled backups, sync and the widget refresh cannot be stopped midway: they carry no button.
“Unconfirmed”. A task that has been in the list for over six hours is marked this way. It is not removed automatically, because a REPAIR on a large table really can take that long and making it vanish would be a lie; instead you get “Dismiss” to remove it by hand if you know it is gone.
Keywords: stop, cancel, go to, kill query, unconfirmed, dismiss