Exporting / Importing a Project

This page explains how to write a project out to a JSON file (export) and read one back in (import).

Overview

GalleonQL lets you write the contents of a project out to a single JSON file, or read a project back in from such a file. This is useful for:

Backup: keep an important project saved as a file
Sharing: hand a project to your team or someone else (e.g. via Git)
Portability: move a project to another machine

Here, a "project" includes its shared headers and shared variables, its environments (connection profiles), and its collection tree (folders, requests, and favorites). For details on the terms, see Key terms.

Prerequisites

The desktop app is running (this uses your OS file dialog).
You perform these steps from the project selector menu in the top bar (not from inside the project edit drawer).

What is and isn't included

An exported file includes / excludes the following.

Included	Not included
Project name / color / shared headers / shared variables	Auth secrets (Bearer tokens, Basic passwords, etc.)
Environment name / color / request URL / variables / headers / auth method only	Request history
Collection tree (folders, requests, favorites)	Drafts of open tabs
Request auth: enabled/disabled + method only	Schema cache

⚠️ Auth tokens and passwords are not written to the file. This is by design, so that you don't accidentally share your secrets. After importing, re-enter your token and other secrets under the environment's "Auth" settings.

Steps

Export (write out a specific project)

Click the project name in the top bar to open the project selector menu.
Press the ↗ (Export this project) button on the right of the project row you want to write out.
In the OS save dialog, choose the destination and file name (the default file name is ProjectName.galleonql.json).
A success message appears at the bottom of the menu (it notes that auth secrets are not included).

The pencil (✎ Edit this project) button is for editing the name, color, shared variables, and so on. It is a separate operation from export.

Import (read in as a new project)

You can import from the same menu even when you have no projects at all.

Click the project name in the top bar to open the project selector menu.
Press Import from JSON at the bottom of the menu.
In the OS file picker, choose the .json file to read in.
The file is validated and (if needed) its format is converted, then it is added as a new project.
The newly added project becomes selected. Follow the notice and re-enter your auth secrets if needed.

Key points

Import always adds a new project. It never overwrites an existing project. If a project with the same name already exists, it is renamed with a parenthesized number, such as ProjectName (2).
↗ (Export) is always available, even for a project that is beyond your slots. Even a project you can no longer "select and use" because it exceeds your slot limit can still have its data rescued as JSON. For how beyond-slot projects behave, see Project slots and plans.
Favorites (★) are preserved as the favorite state of requests and are restored after import.

When the file format is newer / older, it is handled as follows.

File format	Behavior
Newer than the app you're using	Import is aborted and you are asked to update the app
Older than the app you're using	Automatically converted to the current format; missing items are filled with defaults
Same as current	Read in as-is

Troubleshooting

Symptom	What to do
"Please update the app" is shown	The file uses a newer format. Update the app, then import again
"Unsupported format" is shown	Check that the file is a project JSON exported by GalleonQL (files from other tools cannot be read)
"Cannot read as JSON" is shown	Check that the file isn't corrupted (you can test by opening it in a text editor)
You canceled the dialog	Nothing changes (and no error is shown)
Sending after import gives an auth error	Auth secrets are excluded from export. Re-enter the Bearer / Basic secret under the environment's "Auth" settings (this is expected behavior)