Skip to content

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.

Reference20 min read

cms-orbit is the command line that comes with the SDK. It works with your spaces through the 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.

Shell
npx cms-orbit loginnpx 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 teach them which command to use, to try changes with --dry-run first, and to leave flags such as --publish to you.

Commands

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

--server, CMS_ORBIT_SERVER
Means
Where you sign in
Default
https://app.bifrostorbit.com/cms
--api, ORBIT_API
Means
The Management API
Default
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.

--organisation
Default
ORBIT_ORGANISATION, or your only organisation
--space
Default
CMS_SPACE_ID or ORBIT_SPACE, or the only space
--environment
Default
Staging, so nothing changes in production unless you ask
--region
Default
The first region
--locale
Default
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.

Shell
npx cms-orbit schema initnpx cms-orbit schema validatenpx cms-orbit schema diffnpx cms-orbit schema push
cms-orbit schema init
Does
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
Does
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
Does
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
Does
Shows the diff, asks, and applies it
cms-orbit schema rollback
Does
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:

cms/schema/components/trip-hero.tsTypeScript
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). 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.

cms-orbit components pull
Does
Writes the space's components to cms/components/<key>.json (or --out). --only trip-hero,gear-list pulls only those
cms-orbit components push
Does
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
Shell
npx cms-orbit components pull --only trip-heronpx 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 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:

Shell
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.

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

cms-orbit content find
Does
Lists entries as a table, or one JSON object per line with --json
cms-orbit content pull [folder]
Does
Writes each entry's draft to a JSON file, cms/content by default
cms-orbit content push [folder]
Does
Saves the files back as drafts, and reports what someone else changed first
cms-orbit content validate [folder]
Does
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, best first, when the environment has it switched on; otherwise it says so and matches by words.

Shell
npx cms-orbit content find --type trip --meaning "paddling between islands" --limit 5npx 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.

Shell
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.

Shell
npx cms-orbit content push --dry-runnpx 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 requiredChecked 42 entries: 1 with problems.

Media

cms-orbit media pull [folder]
Does
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\
Does
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.

Shell
npx cms-orbit media push ./photos/lofoten-ridge.jpg --folder "Trips"npx cms-orbit media push https://northwilds.com/images/sarek-traverse.jpgnpx 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

cms-orbit taxonomies pull [folder]
Does
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\
Does
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>
Does
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, 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:

Shell
npx cms-orbit taxonomies delete difficultynpx 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.

cms-orbit migrations generate <key>
Does
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>
Does
Runs it on the drafts of matching entries. --dry-run shows each entry's changes
cms-orbit migrations rollback <run>
Does
Puts back the drafts a run changed
cms-orbit migrations list
Does
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:

cms/migrations/2026-11-15-hero.tsTypeScript
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;}
Shell
npx cms-orbit migrations run cms/migrations/2026-11-15-hero.ts --dry-runnpx 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, and points it at your space.

Shell
npx cms-orbit project create northwilds-site --framework nextjs --create-keycd northwilds-sitenpm installnpm 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 in CMS Orbit is the record for your organisation; these are for you.

Exit codes and errors

0
Means
Done
1
Means
It failed, for example a request was refused or you are not signed in
2
Means
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), so a retried change is made only once.

Was this page helpful?

Read next