# CMS Orbit CLI

> Every cms-orbit command: sign in, keep the schema in code, pull and push content, media and taxonomies, run migrations, start a project, and read the log of what the command line changed.

Source: https://docs.bifrostorbit.com/cms/developers/cli/

`cms-orbit` is the command line that comes with the [SDK](https://docs.bifrostorbit.com/cms/developers/sdk/). It works with your spaces through the [Management API](https://docs.bifrostorbit.com/cms/developers/management-api/), as you or as a management token. Run it with `npx`, or add `@bifrost-orbit-cms/sdk` to your project and call it from `package.json` scripts.

```bash
npx cms-orbit login
npx cms-orbit user
```

`npx cms-orbit --help` lists every command, and `--help` after any command or group shows its options. Commands that answer with data take `--json`, which prints only the JSON on standard output, so you can pipe it into other tools.

Coding agents such as Claude Code, Codex and Cursor can run these commands for you. The [agent skills for CMS Orbit](https://docs.bifrostorbit.com/cms/developers/agent-skills/) teach them which command to use, to try changes with `--dry-run` first, and to leave flags such as `--publish` to you.

## Commands

| Command | Does |
| --- | --- |
| `cms-orbit login` | Signs you in to CMS Orbit in your browser |
| `cms-orbit login --token <token>` | Stores a `cms_mt_` management token instead. Pass `-` to read it from standard input, so it stays out of your shell history |
| `cms-orbit logout` | Signs out and forgets the stored credentials. `--all` signs out of every server |
| `cms-orbit user` | Who you are signed in as, your organisations, the server and where its data is kept |
| `cms-orbit signup` | Opens the page to create a Bifröst Orbit account |
| `cms-orbit schema init` | Writes the space's content types and components as TypeScript files |
| `cms-orbit schema validate` | Checks local schema files for mistakes before anything is sent |
| `cms-orbit schema diff` | Shows what differs between your files and the space, or another space |
| `cms-orbit schema push` | Applies your schema files after showing the changes, with a snapshot to undo |
| `cms-orbit schema rollback` | Undoes a schema push from its snapshot |
| `cms-orbit components pull` / `push` | Components alone, as one JSON file each |
| `cms-orbit types generate` | Types for TypeScript, PHP, Swift or Kotlin, from the space or local schema files |
| `cms-orbit languages list` / `pull` | A space's regions and languages, with prefixes, currencies and time zones |
| `cms-orbit content find` | Searches entries by type, folder, address, status, text or meaning |
| `cms-orbit content pull` / `push` | Entries as JSON files and back as drafts, with conflict checks |
| `cms-orbit content validate` | Checks entries against the schema |
| `cms-orbit media pull` / `push` | Files with their alt text, folders and focus point |
| `cms-orbit taxonomies pull` / `push` / `delete` | Taxonomies and their terms, as JSON or CSV |
| `cms-orbit migrations generate` / `run` / `rollback` / `list` | Scripts that change existing content, with a dry run and a way back |
| `cms-orbit project create` | Starts a website from one of our starters, connected to your space |
| `cms-orbit logs list` | What the command line changed, newest last. `--space`, `--since 7d` and `--limit` narrow it down |
| `cms-orbit logs prune` | Removes log entries older than `--keep`, 30 days by default |
| `cms-orbit reports list` | The reports that bulk commands wrote, with where each file is |
| `cms-orbit reports prune` | Removes reports older than `--keep`, 30 days by default |
| `cms-orbit generate` | The same as `types generate`. See [SDKs](https://docs.bifrostorbit.com/cms/developers/sdk/) |
| `cms-orbit import` | Imports an import file. See [Import content with the Management API](https://docs.bifrostorbit.com/cms/developers/import-content/) |
| `cms-orbit promote` | Publishes a whole language or folder in another environment |

## Sign in

`cms-orbit login` opens your browser at CMS Orbit's sign-in. Sign in as you always do, check what the command line asks for, and select **Allow**. The browser then says you can close the tab, and the terminal says who you are signed in as.

- **It acts as you.** The command line can do what you can do in CMS Orbit, in every organisation you belong to, with your role's permissions there. If your role changes, so does what it can do.
- **Recorded:** what it changes is recorded as you, marked "(command line)", in the audit log and in each page's history. Signing in is recorded in the audit log of each of your organisations.
- **What stays in the browser:** creating management tokens and handing over an organisation.
- **How long:** it renews itself each hour while you use it, and ends after 30 days without use, when you run `cms-orbit logout` or sign it out in CMS Orbit, or when you lose access to CMS Orbit.
- **Only on your computer:** the sign-in returns to an address on your own computer (`127.0.0.1`), which only the command line is listening on. If no browser opens, for example over SSH, open the link it prints; `--no-browser` only prints it.

Your credentials are kept in `~/.config/cms-orbit/credentials.json` (or `$XDG_CONFIG_HOME/cms-orbit`, or `%APPDATA%\cms-orbit` on Windows), readable only by you, with one sign-in per server. The command line never prints a token.

## See and end your sign-ins

Each computer where you ran `cms-orbit login` is a sign-in of its own. To see them, open the menu under your name at the bottom left of CMS Orbit and choose **Your account**. Under **Command line**, each sign-in shows when it signed in, when it was last used and when it expires if it is not used again.

- **Sign out** next to a sign-in ends it at once, for every organisation you belong to. Its next command answers that you need to sign in again.
- **Sign out everywhere** ends every sign-in of the command line, after you confirm. Use it if you have lost a computer or think a sign-in was copied.
- **Organisation owners and administrators** see the sign-ins of everyone in the organisation on its **Management tokens** page, under **Command-line sign-ins**, and can sign out anyone ranked below them. As a sign-in belongs to the person rather than to one organisation, signing it out there ends it everywhere too. To stop someone signing in again, remove them from the organisation.

Signing in and signing out are recorded in the audit log of each organisation the person belongs to. To sign in again, run `cms-orbit login`.

## Credentials and servers

Each command uses the first of these it finds:

1. `--token cms_mt_…` on the command
2. `ORBIT_TOKEN` in the environment, `.env.local` or `.env`
3. What `cms-orbit login` stored for the server

So CI uses its management token even on a machine where someone is signed in. Without any of them, a command asks you to run `cms-orbit login`.

| Setting | Means | Default |
| --- | --- | --- |
| `--server`, `CMS_ORBIT_SERVER` | Where you sign in | `https://app.bifrostorbit.com/cms` |
| `--api`, `ORBIT_API` | The Management API | `https://api.bifrostorbit.com/cms/manage/v1` |

For staging, set `ORBIT_API=https://api-stage.bifrostorbit.com/cms/manage/v1`, and the command line signs in at `https://stage.bifrostorbit.com/cms`. The command line reads these settings from the environment first, then from `.env.local` and `.env` in the folder you run it in.

## Choose a space

Commands that work in a space take these options. Each takes an id or a name you'd type: a slug for organisations and spaces, a key for environments and regions, a code for languages.

| Option | Default |
| --- | --- |
| `--organisation` | `ORBIT_ORGANISATION`, or your only organisation |
| `--space` | `CMS_SPACE_ID` or `ORBIT_SPACE`, or the only space |
| `--environment` | Staging, so nothing changes in production unless you ask |
| `--region` | The first region |
| `--locale` | The region's default language |

The command says which it chose, for example `Using Northwilds › Northwilds › staging › europe › en-GB`. A name that doesn't exist lists the ones that do. A management token belongs to one organisation, so give it the organisation's id, shown on the **Management tokens** page.

## Schema

`cms-orbit schema` keeps your space's content types and components in your repository as TypeScript files, one per content type and component, so changes to the schema are reviewed in pull requests and made in the same commit as the components that render them. The schema belongs to the space, so every environment of the space shares it and these commands take no `--environment`.

```bash
npx cms-orbit schema init
npx cms-orbit schema validate
npx cms-orbit schema diff
npx cms-orbit schema push
```

| Command | Does |
| --- | --- |
| `cms-orbit schema init` | Writes the space's schema to `cms/schema/` (or `--out`): `content-types/<key>.ts`, `components/<key>.ts` and an `index.ts`. It won't overwrite a folder that already holds a schema unless you pass `--force` |
| `cms-orbit schema validate` | Checks the folder without changing anything: keys, names, field types, options, conditions, main headings, and references between content types and components. `--remote` also checks the field types against the server. Exits with `1` when there is an error |
| `cms-orbit schema diff` | Lists what `push` would add, change or remove, field by field. `--from-space <slug>` compares with another space instead of the folder, `--uses` counts the entries holding values in what would be removed, `--json` answers in JSON, and `--exit-code` exits with `1` when there are differences |
| `cms-orbit schema push` | Shows the diff, asks, and applies it |
| `cms-orbit schema rollback` | Lists the snapshots taken by `push`. With a snapshot, or `latest`, puts back what that push changed |

Each file exports one definition, typed so your editor completes the settings and field types:

```ts
// cms/schema/components/trip-hero.ts
import type { CmsComponentDefinition } from "@bifrost-orbit-cms/sdk";

export default {
  key: "trip-hero",
  name: "Trip hero",
  group: "Trips",
  fields: [
    { key: "heading", name: "Heading", type: "text", required: true },
    { key: "season", name: "Season", type: "select", options: [{ label: "Summer", value: "summer" }, { label: "Winter", value: "winter" }] },
    { key: "photo", name: "Photo", type: "asset" },
  ],
  mainHeading: "heading",
} satisfies CmsComponentDefinition;
```

Settings left at their defaults are left out, so a file holds only what you chose. A file can import types but no code: it is read on its own. Keys never change in CMS Orbit, so renaming a key in a file removes the old definition or field and adds a new one.

### Push safely

- **It shows the diff first** and asks before changing anything. `--yes` applies without asking, for CI; without a terminal it won't wait for an answer and asks for `--yes`. `--dry-run` shows the diff and stops.
- **It checks the files first** and pushes nothing while `validate` finds an error.
- **It won't lose content by accident.** Removing a field that entries hold values in, or changing its type, is refused with how many entries are affected, unless you pass `--allow-destructive`. The values stay in the entries, so a rollback brings them back.
- **It never removes what entries use.** A content type or component still used by entries stays, and the push stops before changing anything.
- **It needs the right role.** Reading the schema needs `schema:read`; pushing needs `schema:manage`, which the Developer, Admin and Owner roles have. Without it, the command says so before asking anything.
- **It can be undone.** Before changing anything it saves a snapshot of the space's schema on your computer and prints the command to roll back, such as `cms-orbit schema rollback 2026-11-15T09-30-00-000Z-schema-push`. A rollback puts back only what that push changed, with the same diff, questions and checks, and takes a snapshot of its own.

Every change is written to the log, and the push writes a report with every result (see [Logs and reports](#logs-and-reports)). To copy the schema of one space to another, run `cms-orbit schema push --space northwilds-test --from-space northwilds`.

## Components

`cms-orbit components` pulls and pushes components alone, as JSON files, one per component, for when you don't keep the whole schema in TypeScript.

| Command | Does |
| --- | --- |
| `cms-orbit components pull` | Writes the space's components to `cms/components/<key>.json` (or `--out`). `--only trip-hero,gear-list` pulls only those |
| `cms-orbit components push` | Adds and changes components to match the files, with the same diff, questions, snapshot and safety as `schema push`. `--only` pushes only those. Components without a file are left alone unless you pass `--delete-missing` |

```bash
npx cms-orbit components pull --only trip-hero
npx cms-orbit components push --only trip-hero --dry-run
```

`cms-orbit schema rollback` undoes a components push too.

## Types

`cms-orbit types generate` writes types for your content types and components, as [`cms-orbit generate`](https://docs.bifrostorbit.com/cms/developers/sdk/) does, with the same options: `--lang` (`ts`, `php`, `swift` or `kotlin`), `--out`, `--include references`, `--namespace` and `--package`. With `--from cms/schema` it reads the schema folder instead of the space, so the types follow the schema in the same commit, before you push:

```bash
npx cms-orbit types generate --from cms/schema --out src/cms/types.ts
```

`cms-orbit generate` keeps working as before.

## Languages

`cms-orbit languages` reads the regions and languages of an environment, staging unless you pass `--environment`.

| Command | Does |
| --- | --- |
| `cms-orbit languages list` | Each region with its address prefix, currency and time zone, and its languages, with the default and fallbacks |
| `cms-orbit languages pull` | Writes the same to `cms/languages.json` (or `--out`), by key and code, for your website to read |

```bash
npx cms-orbit languages pull --environment production
```

```json
{
  "space": "northwilds",
  "environment": "production",
  "regions": [
    {
      "key": "europe",
      "name": "Europe",
      "pathPrefix": null,
      "currency": "EUR",
      "timeZone": "Europe/Oslo",
      "defaultLocale": "en",
      "locales": [
        { "code": "en", "name": "English", "fallback": null, "enabled": true },
        { "code": "nb", "name": "Norsk", "fallback": "en", "enabled": true },
        { "code": "de", "name": "Deutsch", "fallback": "en", "enabled": true }
      ]
    }
  ]
}
```

## Content

`cms-orbit content` works with a space's entries in one language, or every language with `--all-locales`. It reads and saves drafts only: nothing goes live unless you pass `--publish` and your role may publish there.

| Command | Does |
| --- | --- |
| `cms-orbit content find` | Lists entries as a table, or one JSON object per line with `--json` |
| `cms-orbit content pull [folder]` | Writes each entry's draft to a JSON file, `cms/content` by default |
| `cms-orbit content push [folder]` | Saves the files back as drafts, and reports what someone else changed first |
| `cms-orbit content validate [folder]` | Checks entries against the content types and components, in a folder or in the space |

`find` narrows the list with `--type trip`, `--folder trips/norway`, `--path /trips/`, `--status draft`, `--since 7d` (or a date such as `2026-11-01`), `--text lofoten` (the name, address and external ID; add `--deep` to search the fields too) and `--limit`. `--meaning` searches by meaning with [Gravity](https://docs.bifrostorbit.com/cms/developers/search/), best first, when the environment has it switched on; otherwise it says so and matches by words.

```bash
npx cms-orbit content find --type trip --meaning "paddling between islands" --limit 5
npx cms-orbit content find --status draft --since 2d --json | jq -r .url
```

`pull` writes one file per entry, at `<folder>/<region>/<language>/<content folder>/<slug>.json`, with its id, `docVersion` and the draft's `fields`, `components` and `seo`. `--type`, `--folder` and `--since` choose what to pull, and `--published` adds what is live, under `published`, for reference. A `.cms-orbit.json` in the folder says which space and environment it came from.

```bash
npx cms-orbit content pull --folder trips --all-locales
```

`push` goes through every file in the folder, or only `--region` and `--locale`:

- **With an id**, it saves the draft when the file differs from CMS Orbit. When someone changed the entry since you pulled it, it is a **conflict**: nothing is saved, the differences are listed, and you pull it again or merge by hand. Pushes never overwrite someone else's change.
- **Without an id**, it looks for the entry at the file's address, then by its external ID, and saves that one; otherwise it creates a new draft. The content folder must exist already.
- `--dry-run` sends every change to CMS Orbit's own checks without saving anything, and lists each change.
- `--publish` publishes what it saved. Where you may not publish, or a review is needed, it says so and leaves the draft saved.

Each file is updated with the new version after a save, so you can push again. The push writes a report and logs every change. It refuses a folder pulled from another space or environment unless you pass `--force`.

```bash
npx cms-orbit content push --dry-run
npx cms-orbit content push
```

`validate` lists the problems of each entry: required fields left empty, values of the wrong type, choices that don't exist, text that is too long, components a content type or slot doesn't allow, and components the space doesn't have. Fields the schema doesn't have, and deprecated components, are warnings, which fail the command only with `--strict`. Without a folder it checks the space, with `--type` to narrow it down.

```text
europe/en/trips/lofoten-ridge-walk.json (6a91…)
  error   fields.title: Title is required
  error   components[hero-1].fields.image: Photo is required
Checked 42 entries: 1 with problems.
```

## Media

| Command | Does |
| --- | --- |
| `cms-orbit media pull [folder]` | Downloads the library to `cms/media`, in its media folders, with `media.json` holding each file's alt text, title, caption, tags and focus point. `--folder` pulls one media folder |
| `cms-orbit media push <folder\|file\|url>` | Uploads what the library doesn't have, and saves changed metadata from `media.json` |

A file counts as in the library already when its id in `media.json`, its content or its name, folder and size match, so pushing again uploads nothing twice and files already downloaded are not downloaded again. `--folder "Gear photos"` puts a single file, a web address, or files `media.json` doesn't list into that media folder, made when missing. `--dry-run` lists what would be uploaded or changed.

```bash
npx cms-orbit media push ./photos/lofoten-ridge.jpg --folder "Trips"
npx cms-orbit media push https://northwilds.com/images/sarek-traverse.jpg
npx cms-orbit media pull --folder Trips
```

When the plan's media storage is full, the push stops at that file, says how much space it needed, and lists the rest as skipped. Empty the bin or delete files you no longer need, or an owner can upgrade under **Billing** in Orbit.

## Taxonomies

| Command | Does |
| --- | --- |
| `cms-orbit taxonomies pull [folder]` | Writes each taxonomy with its terms to `cms/taxonomies/<key>.json`. `--key` pulls one; `--csv` writes CSV with every language and region instead |
| `cms-orbit taxonomies push [folder\|file]` | Creates missing taxonomies and adds, changes and orders terms by their value. `--remove-missing` deletes terms a file leaves out; `--dry-run` only reports |
| `cms-orbit taxonomies delete <key>` | Deletes a taxonomy with its terms, after you confirm |

```json
{
  "key": "activity",
  "name": "Activity",
  "description": "What a trip is mostly about",
  "terms": [
    { "value": "hiking", "label": "Hiking", "labels": { "nb": "Fotturer", "de": "Wandern" } },
    { "value": "sea-kayaking", "label": "Sea kayaking", "regions": { "europe": { "labels": { "de": "Seekajak" } } } }
  ]
}
```

CSV files take the format described under **Terms as CSV** in the [Management API](https://docs.bifrostorbit.com/cms/developers/management-api/), so you can edit them in a spreadsheet; push imports them the same way as the **Import** button.

`delete` refuses while a content type or component has a field that uses the taxonomy, naming them, unless you pass `--force`. It asks you to type the key, or takes `--yes` in scripts. CMS Orbit has no bin for taxonomies, so the command keeps a copy on your computer first and prints how to put it back:

```bash
npx cms-orbit taxonomies delete difficulty
npx cms-orbit taxonomies push ~/.config/cms-orbit/backups/<space>/<time>-taxonomy-difficulty.json
```

## Migrations

A migration changes many entries in one go, such as renaming a field's values in every `hero` block. It is a TypeScript file with one function.

| Command | Does |
| --- | --- |
| `cms-orbit migrations generate <key>` | Writes `cms/migrations/<date>-<key>.ts` for a component or content type, with its fields typed. `--name`, `--dir`, and `--kind component` or `content-type` |
| `cms-orbit migrations run <file>` | Runs it on the drafts of matching entries. `--dry-run` shows each entry's changes |
| `cms-orbit migrations rollback <run>` | Puts back the drafts a run changed |
| `cms-orbit migrations list` | The runs made in the space from your computer |

A component migration is called with every block of that type, at any depth, and returns the changed block, or `null` to remove it. A content type migration is called with each entry of that type and returns it with changed `fields`, `components` or `seo`:

```ts
// cms/migrations/2026-11-15-hero.ts
export const target = { component: "hero" } as const;

export default function migrate(block: Block<HeroFields>): Block<HeroFields> | null {
  if (block.fields.size === "large") block.fields.size = "full";
  return block;
}
```

```bash
npx cms-orbit migrations run cms/migrations/2026-11-15-hero.ts --dry-run
npx cms-orbit migrations run cms/migrations/2026-11-15-hero.ts
```

A real run saves a snapshot of every draft it is about to change on your computer first, then saves the new drafts, each with the version it read, so an entry someone saves at the same moment is reported as a conflict rather than overwritten. Nothing is published unless you pass `--publish`. It writes a report, logs each entry, and prints the run's id.

`rollback` takes that id, its end, or `last`, and puts each entry's draft back from the snapshot. An entry changed since the run is left alone and reported, unless you pass `--force`. Rolling back never publishes; if the run published, publish again to put the old version live. `--dry-run` shows what would be put back.

Migrations need Node.js 22.18 or later to run TypeScript; on older versions, write them as `.mjs`.

## Start a project

`cms-orbit project create <folder>` makes a website project from one of the starters, the finished code of the [quickstarts](https://docs.bifrostorbit.com/cms/developers/quickstarts/), and points it at your space.

```bash
npx cms-orbit project create northwilds-site --framework nextjs --create-key
cd northwilds-site
npm install
npm run dev
```

- `--framework`: `nextjs`, `react`, `astro`, `nuxt`, `vue`, `sveltekit`, `angular`, `laravel` or `symfony`. Without it, the command asks.
- `--template website`: the ready-made website for the space templates, with menus, contact details and every template component (Next.js).
- It writes the env file the starter reads (`.env.local` for Next.js, `.env` for Nuxt and others) with the Delivery API address, the region (`--region`, the first by default) and a public key for the environment (`--environment`, staging by default).
- The key: `--public-key cms_pk_…` uses yours, `--create-key` creates one if your role may manage delivery keys, and in a terminal the command asks. Without one, the env file has an empty key to fill in from **Configuration › API keys**.
- `--install` installs the dependencies afterwards; otherwise nothing is installed. `--from` copies a starter from a folder instead of downloading it from GitHub.

## Logs and reports

Every command that changes something writes a line to a log on your computer, one file per space, with the time, the command and what it changed, so you can look back with `cms-orbit logs list`. Commands that change many things at once also write a report with every result, a JSON file whose path they print. Both are kept next to your credentials until you prune them. The [audit log](https://docs.bifrostorbit.com/cms/editors/organisation-pages/) in CMS Orbit is the record for your organisation; these are for you.

## Exit codes and errors

| Code | Means |
| --- | --- |
| `0` | Done |
| `1` | It failed, for example a request was refused or you are not signed in |
| `2` | The command or its options were wrong; the usage follows the error |

Errors start with `cms-orbit:` and say what to do next. Requests that meet `429` or `503` are tried again, waiting as long as CMS Orbit asks, and every change carries an `Idempotency-Key` (see the [Management API](https://docs.bifrostorbit.com/cms/developers/management-api/)), so a retried change is made only once.
