What GalleonQL Is / Installation and Launch

This page introduces what kind of app GalleonQL is, and explains how to install it and launch it for the first time on each OS (macOS / Windows / Linux).

What GalleonQL Is

GalleonQL is a desktop API client dedicated to GraphQL. Think of it as a GraphQL-oriented replacement for Postman or Insomnia (which target REST). You use it in roughly the following flow:

1. Import the schema (the definitions of types and fields) from the GraphQL endpoint you connect to,
2. Browse that imported schema as documentation while you work,
3. Build a query step by step, and
4. Switch between multiple connection targets (environments) and send the query, then inspect the response.

The interaction model grows a query by grafting on branches with add Query / add Child — a nod to grafting in horticulture (graft), building up your query one level at a time.

GalleonQL runs as a desktop app, and HTTP requests to external endpoints are issued from the app itself (the desktop process). Because of this it is not subject to the browser's CORS restrictions, so even an internal API that a browser cannot reach directly can be imported from and sent to, as long as your PC can reach it.

The key terms (environment, schema, leaf and branch, environment variables vs. GraphQL variables, and so on) are collected in Key Terms. Reading through it once before you start will make everything easier to follow.

Supported Platforms

GalleonQL is distributed for the following three operating systems.

About code signing (important): The binaries currently distributed are not code-signed (unsigned). Because of this, your OS's security features will show a warning the first time you launch the app. Follow the steps in "First Launch (Handling Unsigned Binaries)" below to start it. The warning is about the app being unsigned; if you follow the steps, it will launch.

Installation

GalleonQL is distributed from the Releases page of the public repository trimixjp/GalleonQL.

1. Open the Releases page.
2. From the latest release, download the asset that matches your OS.
   • macOS: an archive containing a .dmg or .app
   • Windows: an installer (.msi / .exe) or an executable
   • Linux: a .AppImage or .deb
3. Open the downloaded file following the "First Launch" steps below.

For the changes in each version, see the release notes on the Releases page.

First Launch (Handling Unsigned Binaries)

Because the binaries are unsigned, the following per-OS step is required only the first time. Once you allow it, you can launch it normally by double-clicking from the second time onward.

macOS

On macOS, a downloaded app is given a quarantine attribute, and a normal double-click may show "cannot be opened." Launch it in one of the following ways.

• Method A (open via right-click): Right-click (or Control-click) the app (GalleonQL.app) and choose "Open" from the menu. If a confirmation dialog appears, press "Open" once more. Once you open it this way, you can launch it normally afterward.

• Method B (remove the quarantine attribute in the terminal): If the above still does not launch, remove the app's quarantine attribute in the terminal. Adjust the path to wherever you placed the app.

  xattr -dr com.apple.quarantine /Applications/GalleonQL.app
  

Windows

On Windows, when you try to launch an unsigned executable, Microsoft Defender SmartScreen may show a blue screen that says "Windows protected your PC."

1. Click "More info" on the screen.
2. Click the "Run anyway" button that appears.

This lets it launch. Run it only after confirming that you recognize where the file came from (that it was downloaded from the public repository's releases).

Linux

On Linux, give the downloaded .AppImage execute permission before launching it.

chmod +x GalleonQL_*.AppImage
./GalleonQL_*.AppImage

• GalleonQL's screen rendering requires webkit2gtk-4.1. If you get an error at launch that a library cannot be found, install webkit2gtk-4.1 (the package name varies by distribution) with your distribution's package manager.
• If you use the .deb, install it with your distribution's standard method (its dependencies are installed along with it).

The Screen After Launch

When it starts, you see a three-pane layout like the following. The detailed operations are explained on each feature page; here, just get an overall sense of the layout.

• The two-row bar at the top
  • Row 1: multiple request tabs (add a new tab with +), the project / environment selector, and Settings (⚙).
  • Row 2: the HTTP method (POST / GET, etc.), the endpoint URL resolved from the selected environment, the Send button, and the toggle for the documentation panel on the right.
• The left rail (a thin vertical strip): icons to switch between Collections / History.
• The explore panel: projects, environments, and collections, plus request history.
• Request / Response: build the query in the center (the Query / Auth / Headers tabs) and inspect the send results.
• The documentation (Schema) panel: the type catalog of the imported schema. From here you can add fields to the query builder.

You can change the display theme (Dark / Light / System), the font size, and the screen layout from Settings (⚙). The default is the dark theme.

The environments you register, the environment you last selected, and the schemas you imported before are saved automatically and restored on the next launch. You do not need to re-enter URLs or headers every time.

The first time you launch the app, you may see an invitation to help improve GalleonQL by sharing anonymous usage analytics. Whichever you choose, you can change it later at any time from Settings. See Usage Analytics for details.

Next Steps

1. First, prepare a connection target. See Registering and Switching Environments to register and select an environment (connection profile) that holds an endpoint URL, authentication, and headers.
2. Import the GraphQL schema for the selected environment. See Importing a Schema.
3. For how to read the imported schema, see Browsing the Schema Documentation.
4. For how to build a query from the schema, see Query Builder; for how to send the query you built and read the response, see Sending Queries and Reading Responses.

If you get stuck on terminology, you can return to Key Terms. The full table of contents is reachable from the index.