# Galerne documentation # Galerne documentation > What Galerne is, how its parts fit together, and where to start. Galerne is a headless CMS hosted in the European Union. You describe your content model in code, people edit content in the studio, sites read it through a JSON API, and agents read and write it through an MCP server. Every project has its own database. ## How the parts fit | Part | What it is | Where | |---|---|---| | Studio | The editing app: documents, media, branches, reviews, comments, settings | `https://studio.galerne.cloud` | | API | Delivery, writes, media, webhooks, export and import, per project | `https://api.galerne.cloud/p//v1` | | MCP server | The same tools for agents, over streamable HTTP | `https://api.galerne.cloud/p//mcp` | | CLI | `galerne`: schema deploys, content, branches, export, import, a local MCP server | `npm i -g @galerne/cli` | | Client | A typed TypeScript client with no runtime dependencies, plus small Python and PHP clients | `npm i @galerne/client` | The API, the MCP server and the CLI share one tool registry: one definition per operation, with the same inputs, permissions and errors everywhere. The [MCP tools](/docs/tools.md) page lists all of them. ## Start here - [Quickstart](/docs/quickstart.md): create a project, deploy a schema, query it from a site. - [Agent quickstart](/docs/agent-quickstart.md): create a project and a token, give one prompt with your brief to an agent, and it builds and publishes the whole site. - [Full site tutorial](/docs/tutorial.md): a hosted site with two languages, a GitHub data source, review and a release, by hand or with an agent. - [Schema](/docs/schema.md): every field type and option of `galerne.config.ts`. - [Query API](/docs/query.md): filters, ordering, projections, references, languages and branches. - [Agents and permissions](/docs/agents.md): connect Claude, Cursor or ChatGPT, and set what each agent may do. - [Branches and review](/docs/branches.md): how changes wait, merge and go live. [Everything Galerne does](/platform) walks through each capability with a short example. ## By topic - Content: [schema](/docs/schema.md), [query API](/docs/query.md), [media](/docs/media.md), [languages and translations](/docs/translations.md), [the studio](/docs/studio.md). - Workflow: [branches and review](/docs/branches.md), [comments and history](/docs/comments-history.md), [scheduling and releases](/docs/scheduling.md). - Agents: [agents and permissions](/docs/agents.md), [MCP tools](/docs/tools.md). - Integrate: [HTTP API](/docs/api.md), [clients](/docs/client.md), [Next.js kit](/docs/nextjs.md), [webhooks](/docs/webhooks.md), [event stream](/docs/events.md), [data sources](/docs/sources.md), [CLI](/docs/cli.md), [site settings](/docs/site.md), [visual editing](/docs/visual-editing.md). - Sites: [sites and code](/docs/sites.md), [site template](/docs/site-template.md), [design browser](/docs/design-browser.md). - Move: [migrating](/docs/migrate.md), [export format](/docs/export.md). - Account: [members and tokens](/docs/members.md), [SSO and SCIM](/docs/sso.md), [limits and plans](/docs/limits.md), [billing](/docs/billing.md). ## Words we use - **Project**: one content space with its own database, members, tokens and plan. Its slug appears in every URL. - **Document**: one entry of a type, with a draft and, once published, a published version. - **Branch**: a set of changes that waits until someone promotes it into `main`. `main` is the live content. - **Perspective**: `published` reads what sites see; `drafts` reads the latest edits. - **Member**: a person or an agent in a project, with a role. - **Token**: a `gal_…` secret that acts as a member or as the project, with scopes. ## For agents Every page of these docs is also plain Markdown: add `.md` to the URL, or read [llms.txt](/llms.txt) for the index and [llms-full.txt](/llms-full.txt) for everything in one file. --- # Quickstart > Create a project, write galerne.config.ts, deploy the schema, add content and query it from a site. 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](/docs/schema.md). ## 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>({ 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](/docs/query.md) 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](/docs/webhooks.md). ## 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](/docs/agents.md). --- # Build a whole site with an agent > Create a project and a token, give one prompt with your brief to an agent in a terminal, and it builds and publishes the whole site in one go. You create a project and a token, write a short brief, and give it to an agent that works in a terminal, such as Claude Code or Cursor. The agent builds the whole site in one go: hosting, content model, pages in your languages, your colors and fonts. Then it publishes everything and gives you the address. ## 1. Create a project Sign in at `https://studio.galerne.cloud`. On the home page, type a name in the **New project** card and choose **create project**. The studio fills the slug, such as `atelier-rhone`. ## 2. Create a token In **Settings**, **API tokens**, create a token with the `admin` scope, set to expire in a few days. Copy it: it starts with `gal_` and is shown once. ## 3. Give the agent the prompt Start the agent in an empty folder and paste this prompt. Put your slug and token in it, and change the brief to your own site: the more precise it is, the closer the first version gets. ```prompt Build and publish the whole website described below, in one go. Galerne project: atelier-rhone Galerne token: gal_… THE SITE - Who: Atelier Rhône, a design studio of four people in Lyon. Branding, editorial design and websites for cultural places. - Languages: French first, then English. - Pages: home, studio (who we are and how we work), projects (six case studies), team, journal (three posts), contact (address, email, map link). - Tone: warm, precise, plain sentences. No jargon. - References: sites we like are https://www.pentagram.com for the large type and the white space, and https://www.collectifhors.fr for the warmth. Take the spirit, never copy. - Colors: background #F6F1EA, text #1E1B18, accent terracotta #B4532A, a soft second color #D9C7B0. Body text must keep 4.5:1 contrast in light and dark mode. - Fonts: a serif for headings (Fraunces), a sans for text (Inter). - Images: use free photos from public URLs that fit the brief, each with alt text in both languages. - Contact: 12 quai Saint-Vincent, 69001 Lyon, bonjour@atelier-rhone.fr. - Live touch: the home page background follows the weather in Lyon, from Open-Meteo (free, no key): https://api.open-meteo.com/v1/forecast?latitude=45.76&longitude=4.83¤t=weather_code,is_day. A soft warm tone for sun, grey blue for clouds and rain, deep blue at night. Refresh it every 30 minutes, and keep the default background when the API does not answer. HOW TO WORK Galerne is the CMS and the host. Every operation is a tool: GET https://api.galerne.cloud/p//v1/tools lists them with their JSON Schemas, and POST https://api.galerne.cloud/p//v1/tools/ with a JSON body calls one, with the header Authorization: Bearer . Never print the token or write it to a file. Read https://www.galerne.eu/docs/tutorial.md first: its "With an agent" parts show which tools to use. Then do everything directly on main, with no branches and no review, and publish as you go: 1. create_site with the starter template, and follow the build until it is ready; 2. read AGENTS.md and galerne.config.ts with read_file, and deploy the content model; 3. set the colors and fonts with update_theme; 4. write and publish all the content, the settings and the UI strings in both languages; 5. change the code with write_files where the template does not cover the brief, such as the weather background: outside APIs go through fetchExternal in lib/external.ts, as AGENTS.md says; 6. follow each build with build_status and fix it with build_logs when it fails. Do not stop to ask me questions: make reasonable choices and note them. At the end, give me the site's address and a short list of your choices. ``` The agent works for a while. Open the studio during the build: the documents appear as it writes them. ## 4. Open the site When the agent is done, open the address it gives you. **Settings**, **site** shows it too, with **open site**. Want changes? Ask in the same conversation, for example "make the home hero shorter and use the accent on the buttons". Then revoke the token in **Settings**, **API tokens**, or let it expire. ## Go further - Edit everything in the studio: every page, text and image the agent wrote is a document. - For later work with review before anything goes live, connect your agent as an agent member: see [agents and permissions](/docs/agents.md). - The [full site tutorial](/docs/tutorial.md) goes step by step, with branches, review, data sources and releases. - The code is yours: clone it or mirror it to GitHub from **Settings**, **site**. See [sites and code](/docs/sites.md). --- # Build a hosted site from start to finish > A tutorial that builds the site of a small design studio on Galerne, from an empty project to a live site on Tramontane with two languages, data sources from GitHub and OpenAgenda, a code change under review and a scheduled release. Every step works by hand or with an agent. This tutorial builds the website of Atelier Rhône, a small design studio in Lyon. At the end it has pages made of blocks, a blog, a team page, English and French, a list of the studio's open source work synced from GitHub, its upcoming talks synced from its public agenda, and a release that goes live on its own. Galerne hosts the code and Tramontane serves it, both in the EU. Every step can be done in two ways. **By hand** uses the studio, the CLI and your editor. **With an agent** gives a prompt to any agent that speaks MCP, which does the work through the project's MCP server. Both use the same tools, so they end in the same state, and you can change your mind at any step: do one by hand, give the next to the agent, then check its work in the studio. You need: - a Galerne account and a project on the Pro plan (review, releases and scheduling are part of Pro); - Node.js 24 or later and pnpm, for the steps by hand; - an MCP client, for the steps with an agent. Any client works for the content steps; the steps that change code need an agent that works in a terminal; - a GitHub organisation or user with a few public repositories. The project slug in this tutorial is `atelier-rhone`. If yours is different, use it everywhere you see that slug. ## 1. Create the project Only a person can create a project, so this part is the same in both modes: 1. Sign in at `https://studio.galerne.cloud`. 2. On the home page, in the **New project** card, type the name Atelier Rhône. The studio fills the slug `atelier-rhone`. 3. Choose **create project**. The studio opens the new project, and its URL ends with `/p/atelier-rhone`. 4. A new project is on the Free plan. In **Settings**, **usage and plan**, choose Pro. Then give yourself or your agent access to it. **By hand** In **Settings**, **API tokens**, create a token with the `admin` scope and copy it: tokens start with `gal_` and are shown once. Then install the CLI and log in: ```bash npm i -g @galerne/cli galerne login --project atelier-rhone --api https://api.galerne.cloud ``` `galerne login` asks for the token and keeps it in `~/.config/galerne/config.json`. **With an agent** In **Settings**, **agents and MCP**, fill in **New agent**. Name it after your agent, give it the `admin` role so it may create the site and deploy schemas, and set its allowed branches to `agent/*`, and choose **create agent**. Leave **may write on main** and **may promote branches** off: the agent then works on branches and asks you for review, and you decide what goes live. Connect your MCP client to `https://api.galerne.cloud/p/atelier-rhone/mcp`. Clients that support OAuth open a Galerne sign-in page, where you pick the agent. Others take a token: create one on the agent's page and send it as `Authorization: Bearer gal_…`. The server tells the agent to read the schema and the guidelines first, to work on a branch and to finish with a review request. [Agents and permissions](/docs/agents.md) has the steps for each client. ## 2. Create the hosted site The project is empty, so the site starts from the `starter` template: pages made of 16 blocks, a blog, people, settings and UI strings in English and French. Galerne creates a private git repo from the template on its Forgejo server, a site on Tramontane in your Tramontane team, the site's tokens and secrets, and the webhook that refreshes pages on publish. Then it starts the first build. **By hand** In **Settings**, **site**, give the site a name and choose **create site**. The **Builds** card lists the first build, and **show logs** shows it as it runs. It takes a few minutes. When its status is ready, reload the page: Galerne stores the address Tramontane gave the site, wires the webhook, and shows **open site**. **refresh** does the same by hand. If the build failed, read its logs, then choose **rebuild**. **With an agent** ```prompt Create the site for this project with the starter template. Follow the first build until it is ready, then refresh the site and give me its address. ``` The agent calls `create_site`, follows the build with `build_status` and `build_logs`, then calls `refresh_site`. Running `create_site` again is safe: steps already done are kept. Open the address: the site is online and empty, since the project has no content model yet. ## 3. Deploy the content model and the first content The template's content model is in `galerne.config.ts`, in the site repo. It goes to the project once, then content can follow. **By hand** First get a copy of the site code. The repo is private on Galerne's git server, `git.galerne.cloud`, so you clone it with a token: 1. In **Settings**, **site**, find the **Git access** card and choose **create git token**. 2. The studio shows a `git clone` command once. Copy it and run it in a terminal. The command looks like this: ```bash git clone https://bot-4k2j9x0q1m3n:@git.galerne.cloud/sites/atelier-rhone.git ``` - `bot-4k2j9x0q1m3n` is the git user of your project. Galerne makes one per project, named `bot-` followed by the project id, and gives it write access to this repo only. - `` is a git token for that user. It is shown once, works for 30 days, and each **create git token** replaces your previous one. Git keeps it in the remote URL of your clone, so keep the folder private. - `sites/atelier-rhone` is the repo: Galerne names it after the project slug. You can push branches with this token. Pushes to `main` are refused: `main` only changes when you promote a branch in the studio. Then deploy the model and load the template's sample content, which already describes a design studio in Lyon. `npx galerne schema deploy` uses the token you saved with `galerne login` in step 1, and the seed takes the same `admin` token: ```bash cd atelier-rhone pnpm install npx galerne schema deploy GALERNE_PROJECT=atelier-rhone GALERNE_API_URL=https://api.galerne.cloud GALERNE_ADMIN_TOKEN=gal_… pnpm seed ``` Reload the studio: the sidebar now lists the types of the model, such as Pages, Posts, People and Settings. The seed writes pages that use every block, posts, three people, the settings and the UI strings, in both languages, and publishes them. Open the site: it shows the home page. Rename the studio in **Settings** (the singleton in the sidebar), replace the people with your own, and publish. **With an agent** ```prompt Read AGENTS.md and galerne.config.ts in the site repo. On a branch named agent/setup, deploy that content model, then fill the site for Atelier Rhône, a design studio in Lyon, in English and French: the settings, the UI strings, a home page with a hero, our services as cards and a call to action, an about page, a visit page with our address, and two people. Run the checks, then ask me for review. ``` The agent reads the repo with `read_file`, deploys the model on the branch with `deploy_schema` and `branch`, then writes the content with `create_doc` and `patch_doc`. It adds pictures from public URLs with `upload_media`, each with alt text. `check` lists what is missing, such as a translation, and `request_review` sends you the branch. In the studio, open **Branches**, then `agent/setup`. The review shows the schema it deployed and every document it wrote, field by field. Comment where you want changes: the agent reads them with `branch_changes` and fixes them on the same branch. When it looks right, choose **approve**, then **promote and publish**. The model reaches `main` first, then the content, and the site shows it within seconds. People and agents can edit the same document at the same time. Open a page in the studio while the agent writes it, and its changes appear in the fields as it makes them. ## 4. Give the site your look The whole look of the site comes from `theme/tokens.json`: colors, fonts, type sizes, spacing and radii. Each token becomes a CSS variable that every block uses. **By hand** Open **Design** in the studio. Pick the accent color, the fonts and the type scale; the preview shows each block with the new values. Saving commits the tokens on a branch (`design/theme` by default), whose preview rebuilds; ask for review from the branch page and promote it like content. The [design browser](/docs/design-browser.md) at `/_design` on the site shows every block and its variants. **With an agent** ```prompt On a branch named agent/look, give the site a warmer look: a terracotta accent that keeps body text at 4.5:1 contrast in both color schemes, and a serif for headings. Send me the preview link, then ask for review. ``` The agent changes only the tokens it needs with `update_theme`, in one commit. Tramontane builds a preview of the branch, and `preview_url` gives its link. Review it and promote it in the studio. ## 5. Sync the studio's work from GitHub The studio wants a page that lists its open source work. A data source pulls the repositories from the GitHub API into docs of a `repo` type, every hour. The site needs two things first: the `repo` type, and a block that shows those docs. That is a code change and a schema change, so both go on one branch. Git and the content use the same branch name, and one review covers the two. ### Add the type and the block The type, in `galerne.config.ts`: ```ts repo: { title: 'Repository', preview: { title: 'name', subtitle: 'language' }, fields: { name: { type: 'string', required: true }, slug: { type: 'slug', from: 'name', required: true }, description: { type: 'text', localized: true }, url: { type: 'url' }, homepage: { type: 'url' }, language: { type: 'string' }, stars: { type: 'number', integer: true }, topics: { type: 'list', of: 'string' }, updatedAt: { type: 'datetime' }, }, }, ``` The description is localized: the source fills the English one, and the studio writes the French one by hand or with an agent. **By hand** Follow the steps of `AGENTS.md` in the repo, on a new git branch: 1. Copy `blocks/post-list` to `blocks/repo-list`. In `schema.ts`, keep `heading` and `limit` and add `language`, to show only the repositories of one language. 2. In the component, query the `repo` type ordered by `-stars` with `galerne.query`, the way `getPosts` in `lib/galerne.ts` does, and show the name, the description, the language and the stars of each. 3. Add the block to `blocks` and to `page.fields.blocks.of` in `galerne.config.ts`, add the `repo` type above, and add the component to `blocks/index.ts`. 4. Write the examples file, so the block shows in the design browser. ```bash git switch -c site/work pnpm dev # http://localhost:3100 git add -A && git commit -m "Add the repo type and the repoList block" git push origin site/work npx galerne schema deploy --branch site/work ``` The push builds a preview of the branch and opens the content branch `site/work`, so the schema deploys on that branch after the push. In the studio, switch to that branch, create a page named Work with the slug `work` in both languages, add a **repoList** block and save. Then open the branch review: it shows the code changes, the schema diff and the new pages together. **With an agent** ```prompt On a branch named agent/work, add a repo type for our GitHub repositories (name, slug, localized description, url, homepage, language, stars, topics, updatedAt) and a repoList block that lists repositories ordered by stars, with an optional language filter. Follow AGENTS.md. Deploy the schema on the branch, add a Work page in English and French that uses the block, check the build, then ask for a code review. ``` The agent writes the files with `write_files`, deploys the schema on its branch with `deploy_schema`, creates the pages with `create_doc`, and follows the preview build with `build_status`. `request_code_review` asks for one review of the code and the content. Promote the branch in the studio with **promote and publish**. Galerne checks that the code merges into `main`, deploys the branch's schema, publishes the pages, then merges the code, and Tramontane builds production. The Work page is live, and it lists nothing yet. ### Connect the source GitHub answers 60 requests an hour without a token, shared by every caller from the same address. Create a fine-grained token on GitHub with read access to public repositories only, and give it to the source as a secret. Galerne keeps secrets encrypted and never shows them again. This definition fills `repo` docs from the repositories of `your-org`, and keeps them up to date every hour: ```json { "name": "github", "definition": { "title": "GitHub repositories", "type": "repo", "fetch": { "url": "https://api.github.com/orgs/your-org/repos?per_page=100&type=public", "headers": { "Authorization": "Bearer {{secret.TOKEN}}" }, "pagination": { "type": "link" } }, "key": "id", "id": "repo-{{name}}", "fields": { "name": "name", "slug": "name", "description.en": "description", "url": "html_url", "homepage": "homepage", "language": "language", "stars": "stargazers_count", "topics": "topics", "updatedAt": "pushed_at" }, "schedule": { "every": 60 }, "target": "review" }, "secrets": { "TOKEN": "github_pat_…" } } ``` For a user account, the URL is `https://api.github.com/users//repos`. With `"target": "review"`, each run that changes something writes on a branch and asks for review, so nothing reaches the site before someone looks. Use `"main"` to publish each run at once. **By hand** In **Settings**, **data sources**, choose **create source**. Pick the `repo` type, paste the URL, set pagination to `link`, add the header and the secret, and map each field as above. **test** fetches the API and shows the first docs it would write next to the items it read, and writes nothing. Save, then choose **run now**. **With an agent** ```prompt Create a data source named github that fills the repo type from the public repositories of the GitHub organisation your-org, every hour, in review mode. Test it first and show me the first three docs it would write. I will add the GitHub token myself. ``` The agent drafts the mapping, tries it with `test_source`, and saves it with `create_source`. Add the token in **Settings**, **data sources**, then choose **run now**: the agent has no right to publish on `main`, so it cannot start a run there itself. The run writes on a branch named `source/github/-