docs menu

Quickstart

This guide takes you from an empty project to a page that reads published content. It takes about ten minutes. You need Node.js 24 or later.

1. Create a project#

Sign in at https://studio.galerne.cloud with your email address and create a project. Its slug, such as acme, appears in every API URL: https://api.galerne.cloud/p/acme/….

In the project settings, open Tokens and create a token with the admin scope for your own machine and CI. Tokens start with gal_ and are shown once.

2. Install the CLI and log in#

bash
npm i -g @galerne/cli
galerne login --project acme --api https://api.galerne.cloud

galerne login asks for the token, checks it against the API and stores it in ~/.config/galerne/config.json. In CI, set GALERNE_PROJECT, GALERNE_API_URL and GALERNE_TOKEN instead.

3. Write the content model#

In your site's repository:

bash
galerne init
npm i -D @galerne/schema

galerne init writes a sample galerne.config.ts. Replace it with your own types. A small blog looks like this:

ts
import { defineConfig } from '@galerne/schema'

export default defineConfig({
  languages: ['en', 'fr'],
  types: {
    post: {
      title: 'Post',
      preview: { title: 'title', subtitle: 'slug', media: 'cover' },
      fields: {
        title: { type: 'string', required: true, max: 120, localized: true },
        slug: { type: 'slug', from: 'title', required: true },
        cover: { type: 'image', altRequired: true },
        author: { type: 'reference', to: ['person'] },
        publishedAt: { type: 'datetime' },
        body: { type: 'richText', localized: true },
      },
    },
    person: {
      title: 'Person',
      fields: {
        name: { type: 'string', required: true },
        photo: { type: 'image' },
      },
    },
  },
})

Every field type and option is in the schema reference.

4. Deploy the schema#

bash
galerne schema diff      # what would change, and whether it breaks content
galerne schema deploy

A change that breaks existing content, such as removing a field that holds values, needs --force. Existing documents keep their values and show validation errors until someone fixes them. Run galerne schema diff in CI to catch breaking changes in pull requests: it exits with code 1 when there are any.

5. Add content#

Open the studio and create a person and a post, then publish them. You can also do it from the command line:

bash
galerne docs create person '{"name": "Ada"}' --id ada
galerne docs publish ada

6. Query it from your site#

Published content can be read without a token, unless the project turned public reads off. With fetch:

ts
const response = await fetch('https://api.galerne.cloud/p/acme/v1/query', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    type: 'post',
    perspective: 'published',
    order: '-publishedAt',
    limit: 10,
    lang: 'fr',
    fallback: true,
    expand: 1,
    select: ['title', 'slug', 'cover', 'author.name'],
  }),
})
const { items, total } = await response.json()

With the typed client, the result types come from your config:

ts
import { createClient, type DocsOf } from '@galerne/client'
import config from './galerne.config.ts'

const galerne = createClient<DocsOf<typeof config>>({
  project: 'acme',
  apiUrl: 'https://api.galerne.cloud',
  perspective: 'published',
})

const { items } = await galerne.query({ type: 'post', order: '-publishedAt', limit: 10 })
const cover = galerne.mediaUrl(items[0].cover.asset, { w: 1200, fm: 'webp' })

Always pass perspective: "published" from a site. The default perspective is drafts, which needs a token with the read scope. The query reference covers filters, ordering, references and languages.

7. Rebuild on publish#

Add a webhook in the project settings that calls your site's rebuild or revalidation endpoint on doc.published and doc.unpublished. See webhooks.

8. Connect an agent#

Add https://api.galerne.cloud/p/acme/mcp to Claude, Cursor or ChatGPT, sign in, and pick the agent it acts as. The steps per client are in agents and permissions.