# CLI

> The galerne command line tool: log in, write and deploy the schema, manage content and branches, export and import, and run a local MCP server.

`galerne` runs the same tools as the API and the MCP server, from your terminal and from CI.

```bash
npm i -g @galerne/cli
galerne --help
```

## Global options

| Flag | Environment variable | Default | What it sets |
|---|---|---|---|
| `-p`, `--project` | `GALERNE_PROJECT` | the default project saved by `login` | Project slug |
| `--api` | `GALERNE_API_URL` | `http://localhost:4000` | API URL; use `https://api.galerne.cloud` |
| `--token` | `GALERNE_TOKEN` | the token saved by `login` | A `gal_…` token |
| `-b`, `--branch` | `GALERNE_BRANCH` | `main` | Content branch for reads and writes |
| `--json` | | | Machine-readable output |

Flags win over environment variables, which win over the saved configuration. Exit codes: `0` success, `1` failure, `2` wrong usage, `3` authentication, `4` network.

## Log in

```bash
galerne login --project acme --api https://api.galerne.cloud
galerne logout --project acme      # or --all
```

`login` asks for a token (input hidden), checks it with the API and saves it as the default project in `~/.config/galerne/config.json`, readable only by you. `GALERNE_CONFIG_DIR` or `XDG_CONFIG_HOME` move that file. In CI, skip `login` and set the three environment variables.

## Schema

```bash
galerne init                    # writes a sample galerne.config.ts and .env.example
galerne schema diff             # changes against the deployed schema; exit 1 on breaking changes
galerne schema deploy           # deploy; --dry-run, --force for breaking changes, --note "why"
galerne schema deploy -b agent/x  # deploy on a branch: main gets it when the branch is promoted
galerne schema pull             # write the deployed schema to galerne.config.ts (-o, --force, -b for a branch's)
```

With `--branch` or `GALERNE_BRANCH`, `schema deploy` stores the config on that branch and `schema pull` reads the one the branch uses. The CLI looks for `galerne.config.ts`, `.mts`, `.js` or `.mjs` in the current folder, or the file given with `-c`. It must default-export `defineConfig({ … })` from `@galerne/schema`. Deploying needs a token with the `admin` scope.

## Content

```bash
galerne docs list --type post --status draft --search harbour
galerne docs get harbours --format markdown
galerne docs create post --file post.json --id harbours
galerne docs patch harbours --set title="Harbours of Brittany" --set seo.description="…" --rev 7
galerne docs publish harbours
galerne docs unpublish harbours
galerne docs delete harbours
galerne query '{"type":"post","order":"-publishedAt","limit":5}'
galerne media upload cover.jpg --alt "Harbour at dawn"
galerne check --changed --strict
```

`docs create` takes the values as a JSON argument, with `--file`, or from standard input with `-`. `docs patch` takes `--set path=value` and `--unset path` as many times as needed. `check --strict` exits with code 1 when there are warnings too, which suits CI.

## Branches

```bash
galerne branch create agent/translate-de --title "German version"
galerne branch create release/spring --release --publish-at 2027-03-20T08:00:00+01:00
galerne branch list --all
galerne branch changes agent/translate-de
galerne branch review agent/translate-de --note "All pages translated"
galerne branch update agent/translate-de
galerne branch promote agent/translate-de --publish --on-conflict branch
galerne branch close agent/translate-de
```

## Any tool

```bash
galerne tools                                   # the tools your token may call
galerne call get_history '{"id":"harbours"}'    # call one with a JSON input
```

## Export and import

```bash
galerne export --out ./backup                 # export.ndjson, media/, galerne.config.json and .ts
galerne import ./backup --branch restore --deploy-schema
```

`export` writes the [export format](/docs/export.md) into `galerne-export-<project>-<branch>` by default. `--no-media` skips the files; `--force` writes into a folder that is not empty. It exits with code 1 when a media download fails.

`import <dir>` reads an export folder: it uploads the media first, keeping their ids, then the documents in batches of 500. `--deploy-schema` deploys the export's schema first; breaking changes need `--force`.

### Other CMSs

```bash
npm i -g @galerne/migrate
galerne import --from sanity --project-id abc123 --dataset production --source-token sk… --dry-run
galerne export --to wordpress --out ./wp-export --site-url https://example.com
```

| Flag | What it does |
|---|---|
| `--from <cms>` | Import from `sanity`, `contentful`, `storyblok`, `wordpress`, `payload` or `markdown` |
| `--to <cms>` | Export to one of those, or `galerne` |
| `--out`, `-o` | Export folder, default `<cms>-export-<project>` |
| `--dry-run` | Convert and report, write nothing |
| `--since <time>` | Import only what changed since an ISO time |
| `--all-media` | Import files no document uses too |
| any other flag | An option of the source or target, in kebab case (`--project-id` sets `projectId`); `--source-token` sets the source's `token` |

Imports go to `--branch`, or `import/<cms>-<date>` by default, and exit with code 1 when a document fails. The [migration guides](/docs/migrate.md) list the options of each CMS.

## Local MCP server

```bash
galerne mcp --project acme
```

Runs an MCP server over stdio for clients that only start local servers, and forwards every message to the project's MCP server with your token. See [agents and permissions](/docs/agents.md#local-stdio).
