Getting Started

Application overview and main workflow.

Calíope is a native MySQL, MariaDB, Amazon Aurora and PostgreSQL client for macOS, iPad and iPhone. The main workflow revolves around two screens: the Connection Manager, where server profiles are managed, and the Workspace, which opens once a connection is established.

The Workspace contains a sidebar with the schema tree, a tab bar for opening multiple tools simultaneously, and a quick-access toolbar for all available tools.

Keywords: start, overview, introduction, what is, getting started, welcome

One file brings up twelve test servers on your Mac, already seeded.

If you have no server at hand, or you want to see what Caliope can do before pointing it at one of yours, you can bring up the very test environment the app is developed against, on your own Mac. It is a single file and it needs nothing but Docker.

→ Download caliope-testbed.command

What you need. macOS 12 or later, Docker Desktop — free for personal use, at docker.com — and around 2 GB of free disk and memory.

How to start it. The cleanest way is to paste these four lines into Terminal:

cd ~/Downloads
curl -fLO https://caliope.org/caliope-testbed.command
chmod +x caliope-testbed.command
./caliope-testbed.command

If you would rather download it with your browser, two more things are needed, in this order: make it executable (chmod +x on the downloaded file) and open it the first time with right-click › Open instead of a double click, because macOS quarantines whatever a browser downloads. With curl neither applies.

The first run takes a few minutes pulling images, and it tells you what it is doing while it works. When it finishes it prints one report with the addresses, the ports and the credentials.

What it brings up. Twelve servers, picked so that no Caliope tool is left with nothing to show:

Plus an SSH bastion and continuous load generators, so the Dashboard, the slow query log, the process list and the replication monitor have real traffic to show.

You do not type the profiles in. Every run leaves a caliope-testbed-connections.json file next to the launcher, with the twelve nodes as one group. In Caliope: Settings › Connections › Import. Importing merges, so nothing you already have is removed. The user is caliope and the password caliopepass. The two tunnelled profiles ask for their SSH password (tunnel123) the first time, because SSH secrets only ever live in the Keychain.

From the iPad and the iPhone too. Every profile carries the Mac's network address as its alternate, so the same file works on all three devices without editing anything — with the Mac awake, the testbed running, and both on the same network.

The four commands.

Careful with --fresh: it is destructive and it reaches beyond Caliope. It stops every Docker container on your Mac and deletes images, volumes and caches nothing is using, including those of your other projects. It says so and asks for confirmation before touching anything. In exchange it is the only run that offers to download the three sample datasets, one per engine: Sakila for MySQL and MariaDB, Pagila for PostgreSQL and the Atlas sample for MongoDB. Each one is asked for separately.

This is not a server to work on. The passwords are public and written inside the file itself, nothing is encrypted, and everything listens on your machine. It is a testbed: for learning, for trying a tool before you use it on data of your own, and so that a bug report can be reproduced.

Keywords: docker, test, testbed, sample, no server, demo, practice, sakila

Create a profile and establish your first server connection.

Where it is: Connection Manager › + Button

In the Connection Manager, tap the + button in the sidebar to create a new profile. Enter the host, port (3306 by default), username, and password. Tap Test Connection to verify the details before saving.

Once validated, tap Connect to open the Workspace. The profile is saved and will be available in the list for future connections.

Keywords: first time, new connection, profile, host, port, connect

How to use the Tools sidebar, the tabs, the server switcher and the status bar.

The Workspace has three zones: the Tools sidebar on the left, the tab bar with the tools you have open, and the status bar at the bottom.

To open a tool, click its row in the sidebar. Each one opens in its own tab; you can keep several open and move between them with ⌘] and ⌘[. Rows are grouped by theme, and both the order and the groups are adjusted from the ⋮≡ button in the sidebar itself (see Customize the main bar). Each group collapses when you click its header, and the field at the top of the sidebar filters the tools by name (see Filtering and collapsing the Tools sidebar).

Server switcher: the menu with the active server's name sits in the top-left corner (macOS) or to the left of the tab bar (iPad). From there you can switch sessions, add another server or disconnect. Calíope supports several active connections at once.

Hide the sidebar: the title-bar button collapses it and gives the full width to the active tool.

The schema tree is not here: it lives inside the SQL Editor, the only place it is useful.

Offline: the Workspace without a server shows a quick-access strip with what needs no connection — SQL Editor, Snippets, SQLite Editor, File Previewer, Errors and Reports. The chevron at its right end collapses it.

On iPhone and in a narrow window: the tools live in a bottom bar with the first four of your order and a More button for the rest. Which four those are is up to you: reorder the sidebar.

Keywords: workspace, sidebar, tools, tabs, navigation, server switcher, status bar, offline

The navigator's list is decided by the connection, not by a setting you changed.

The tool navigator doesn't always show the same list: it shows what this session can do. On connecting, Calíope works out what that connection knows how to do and hides the rest. What you can't see isn't broken or switched off: it isn't offered.

Hiding it is deliberate. A tool that opens only to say "not here" has already wasted the trip, and a greyed-out row invites you to hunt for the switch that turns it on — and there is none.

Because of the kind of database. A relational server and a document server are not alike: a document session has no SQL editor and no entity-relationship diagram, and a relational one has no collection browser. That never changes, and it isn't a shortcoming of either.

Because of what that connection can do. Two relational servers don't offer exactly the same things either. Sometimes the engine has no such concept, and then the tool will never appear against that server because there would be nothing to show; sometimes Calíope hasn't written it for that engine yet, and it will appear in a later version. Both absences look the same on purpose: what you need to know right now is whether the tool works, not why it doesn't.

Without a connection the navigator shows only what works with no server: the SQL Editor, Snippets, the SQLite Editor, the File Previewer, Errors and Reports — the last one only halfway, because with no server they can be viewed, edited and exported, but not run.

Where else you'll notice. The Go button in this Help can point at a tool your session doesn't offer: then nothing opens and the status bar says so by name. That's an answer, not a failure.

And this Help carries them all. The index doesn't change with the server you're connected to, so you will find topics here for tools your current session doesn't show. If you're missing one, try opening a session against another server: the list is recomputed on every connection.

Keywords: tools, missing, not shown, navigator, availability, engine, session, hidden, Go

Collapse the groups you don't use and type in the field at the top to find a tool by name.

The Tools sidebar groups Calíope's twenty-odd tools by theme. Two things make it shorter.

Collapse a group: click its header. The chevron turns and the group's rows disappear; next to the name you'll see how many tools it is hiding, so nothing gets lost without a trace. Click again to expand it. What you collapse is remembered when you close the app, and it travels to your other Mac, iPad or iPhone if you have iCloud sync on.

Filter: the field at the top of the sidebar leaves only the tools that match what you type. It searches the tool's name, its full catalogue name and the sentence that says what it does, plus the name of its group — so typing the name of a group shows that group whole. Accents don't matter: replication finds Replicación.

While you are filtering, every group with matches is drawn open, even the ones you had collapsed. Nothing you find can stay hidden inside a closed group. Your collapsed groups are not touched: clear the field and everything goes back exactly as it was.

Press Esc or the × to clear the field. The filter is not remembered when you close the app — a sidebar that opens half empty for a reason you don't recall is worse than typing three letters again.

Keywords: sidebar, tools, filter, search, groups, collapse, expand

What works without connecting to any server, and what doesn't.

Calíope includes an offline Workspace accessible even when no server is connected. It is useful for drafting queries and organizing your snippets without needing a connection.

How to access:

From the Connection Manager, without connecting to any server. Where the button is depends on how much room there is: on a wide screen — the Mac and the iPad — it is on the welcome screen, next to «Create profile»; on a narrow one — the iPhone, and the iPad in a split window — that screen is not drawn at all, so it lives in the bottom bar, with the terminal icon.

Tools available in offline mode:
- SQL Editor — write and save SQL, use history and snippets. Queries cannot be executed against a server.
- Snippets — create, edit, and copy your code snippets.
- SQLite Editor — open a .sqlite file from disk and work on all of it: no server needed, because the file is the database.
- File Previewer — look at CSV, JSON, Markdown and the rest without leaving the app.
- Errors — the log is local, and you need to be able to read it precisely when you can't connect.
- Reports — you can view, edit and export results you already had; running one does need a server, and the view says so.

Offline mode banner: a golden strip at the top of the workspace indicates you are in offline mode.

To connect to a server from the offline workspace, tap the Connect to server button in the toolbar or in the top banner. The Connection Manager opens as a floating panel without losing the editor content.

Keywords: offline, offline mode, no server, offline editor, offline workspace, editor without connection, snippets

Displays the result, timing, and progress of ongoing operations.

The status bar appears at the bottom of the Workspace and the SQL editor. It reflects the state of the last executed operation.

Information displayed:
- Result message — descriptive text of the last operation (rows affected, execution time, error).
- Progress — progress bar or loading animation while a query or task is running.
- Percentage — for long operations (such as backups or restores) it shows numeric progress.

Copy the message:

macOS: double-click on the status bar text area to copy the full message to the clipboard. Useful for copying error messages without having to select them manually.

iPad: the same double-tap gesture copies the message.

The status bar is always visible and cannot be hidden.

Keywords: status bar, progress, message, copy message, error, execution time, double click

Reorder and hide the buttons on the editor and results toolbars.

Where it is: SQL Editor › Customize toolbar

The SQL Editor has two toolbars of its own, each customized separately:

- Editor toolbar — above the text area: run, format, comment, history, schema panel…
- Results toolbar — above the grid: export, chart, column profiler, filters…

Opening the customizer
Click the ⋮≡ button (slider.horizontal.3 icon) at the start of the toolbar you want to adjust.

What you can do
- Reorder — drag each button where you want it.
- Hide — uncheck the ones you don't use; their actions stay available from the menus and keyboard shortcuts.
- Reset — restores that toolbar's original layout.

Both toolbars scroll horizontally, so no button is ever out of reach however narrow the window is.

For the Workspace tool launcher, see Customize the main bar.

Keywords: editor toolbar, results toolbar, customize, reorder, hide buttons, drag, sql editor

Reorder the buttons of the Workspace's main toolbar to put your favorite tools first.

Where it is: Workspace › Customize the main toolbar

The navigation sidebar (app launcher) organizes shortcuts to all workspace tools into logical groups for an optimized workflow:

1. Development & Querying — SQL Editor, Query Builder, Snippets, SQL Log, and SQLite Editor.
2. Design & Schema — Catalogs, ER Diagram, Schema Diff, and Object Migration.
3. Diagnostics & Performance — Dashboard, Server Health, SQL Alerts, Replication Monitor, and Binlog Viewer.
4. Server Administration — Server Info, Processes, Users, Backup, and Maintenance.
5. Smart Assistant — AI Assistant.

How to open the customizer
- At the top of the navigation sidebar, you will find the customization button ⋮≡ (slider.horizontal.3 icon).
- Click it to open the customization screen.

What you can do
The customizer offers a hierarchical and fully dynamic control split into two tabs:
- "Reorder Groups" Tab — Drag and drop entire sections to change the category layout, rename them, or even add your own custom groups.
- "Reorder Elements" Tab — Drag and drop individual tools within each group, or tap Move to... to dynamically move any tool to another section.
- Reset — The Reset button restores the native default layout and groups in a single tap.

Persistence and Self-Healing
Your layout is safely stored in UserDefaults (under the key caliope_sidebar_config_macos or caliope_sidebar_config_ipad). If Calíope introduces a new tool in a future update, it will automatically register within its default category without disturbing your personalized order.

Keywords: main toolbar, quick access, nav strip, customize, reorder, buttons, drag, overflow

Work with several MySQL, MariaDB, Aurora or PostgreSQL servers at once without losing each one's context.

Where it is: Server › Add session…

Calíope keeps independent sessions for every connection profile you open. Each session has its own tabs, its own active database, its own query history, and its own layout preferences.

Open a new session
- macOS: menu Server › Add session… or shortcut ⌘⌥N. You can also click New session from the server selector in the top-left corner.
- iPad: open the server selector (icon to the left of the tab bar) and tap Add session.

Switch between sessions
- Use the server selector in the top-left corner (macOS) or in the tab bar (iPad). Each session shows the profile name, the host, and a color dot indicating its status.
- macOS: shortcut ⌘⌥1…9 to jump directly to the first nine sessions.

Per-session state
- Each session remembers the active database, the open tabs, and the query history in QueryLogger.
- SSH and SSL connections are established only once per session; switching sessions does not reconnect.
- The pinned widget follows the profile marked as pinned in Preferences › Widget, regardless of which session is in the foreground.

Close a session
- Close all tabs with the × or use Server › Disconnect. Calíope closes the SSH tunnel if one exists.
- Passwords remain in the Keychain; they are not re-prompted on reconnect unless the profile requires biometric authentication.

Keywords: sessions, multi-session, multiple servers, simultaneous, switch session, server selector, add session, session manager, ⌘⌥N, disconnect

How to open the full help index on each platform.

Where it is: Help › Calíope Help

Calíope's help is available as a dedicated window or panel with an index, search, and section navigation. It opens differently per platform but shows the same content.

macOS: menu Help › Calíope Help or shortcut ⌘?. The help window stays floating and can remain open while you use the rest of the app.

iPad: menu Help › Calíope Help or shortcut ⌘? if you have an external keyboard connected. Help appears as a sheet; close it with the Close button in the upper-right corner or swipe down.

Contextual help (?): every view in the app has a ? button in its top bar that opens the related topic directly. It's the fastest way when you already know which tool you're looking for.

On the web: the same Help is published at https://caliope.org/help/, in the five languages. From there, with “I have Calíope installed” switched on, every topic has an “Open in Calíope” button that opens it in the app; a topic's link has the form caliope://help/<identifier>.

Keywords: help, help center, index, search topic, help menu, ⌘?, documentation, cmd?