# 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<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](/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).
