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.
npx cms-orbit loginnpx cms-orbit usernpx 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 logincms-orbit login --token <token>cms_mt_ management token instead. Pass - to read it from standard input, so it stays out of your shell historycms-orbit logout--all signs out of every servercms-orbit usercms-orbit signupcms-orbit schema initcms-orbit schema validatecms-orbit schema diffcms-orbit schema pushcms-orbit schema rollbackcms-orbit components pull / pushcms-orbit types generatecms-orbit languages list / pullcms-orbit content findcms-orbit content pull / pushcms-orbit content validatecms-orbit media pull / pushcms-orbit taxonomies pull / push / deletecms-orbit migrations generate / run / rollback / listcms-orbit project createcms-orbit logs list--space, --since 7d and --limit narrow it downcms-orbit logs prune--keep, 30 days by defaultcms-orbit reports listcms-orbit reports prune--keep, 30 days by defaultcms-orbit generatetypes generate. See SDKscms-orbit importcms-orbit promoteSign 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 logoutor 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-browseronly 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:
--token cms_mt_…on the commandORBIT_TOKENin the environment,.env.localor.env- What
cms-orbit loginstored 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_SERVERhttps://app.bifrostorbit.com/cms--api, ORBIT_APIhttps://api.bifrostorbit.com/cms/manage/v1For 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.
--organisationORBIT_ORGANISATION, or your only organisation--spaceCMS_SPACE_ID or ORBIT_SPACE, or the only space--environment--region--localeThe 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.
npx cms-orbit schema initnpx cms-orbit schema validatenpx cms-orbit schema diffnpx cms-orbit schema pushcms-orbit schema initcms/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 --forcecms-orbit schema validate--remote also checks the field types against the server. Exits with 1 when there is an errorcms-orbit schema diffpush 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 differencescms-orbit schema pushcms-orbit schema rollbackpush. With a snapshot, or latest, puts back what that push changedEach file exports one definition, typed so your editor completes the settings and field types:
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.
--yesapplies without asking, for CI; without a terminal it won't wait for an answer and asks for--yes.--dry-runshows the diff and stops. - It checks the files first and pushes nothing while
validatefinds 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 needsschema: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 pullcms/components/<key>.json (or --out). --only trip-hero,gear-list pulls only thosecms-orbit components pushschema push. --only pushes only those. Components without a file are left alone unless you pass --delete-missingnpx cms-orbit components pull --only trip-heronpx cms-orbit components push --only trip-hero --dry-runcms-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:
npx cms-orbit types generate --from cms/schema --out src/cms/types.tscms-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 listcms-orbit languages pullcms/languages.json (or --out), by key and code, for your website to readnpx cms-orbit languages pull --environment production{ "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--jsoncms-orbit content pull [folder]cms/content by defaultcms-orbit content push [folder]cms-orbit content validate [folder]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.
npx cms-orbit content find --type trip --meaning "paddling between islands" --limit 5npx cms-orbit content find --status draft --since 2d --json | jq -r .urlpull 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.
npx cms-orbit content pull --folder trips --all-localespush 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-runsends every change to CMS Orbit's own checks without saving anything, and lists each change.--publishpublishes 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.
npx cms-orbit content push --dry-runnpx cms-orbit content pushvalidate 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.
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]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 foldermedia.jsonA 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.
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 TripsWhen 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]cms/taxonomies/<key>.json. --key pulls one; --csv writes CSV with every language and region instead--remove-missing deletes terms a file leaves out; --dry-run only reportscms-orbit taxonomies delete <key>{ "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:
npx cms-orbit taxonomies delete difficultynpx cms-orbit taxonomies push ~/.config/cms-orbit/backups/<space>/<time>-taxonomy-difficulty.jsonMigrations
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>cms/migrations/<date>-<key>.ts for a component or content type, with its fields typed. --name, --dir, and --kind component or content-typecms-orbit migrations run <file>--dry-run shows each entry's changescms-orbit migrations rollback <run>cms-orbit migrations listA 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:
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;}npx cms-orbit migrations run cms/migrations/2026-11-15-hero.ts --dry-runnpx cms-orbit migrations run cms/migrations/2026-11-15-hero.tsA 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.
npx cms-orbit project create northwilds-site --framework nextjs --create-keycd northwilds-sitenpm installnpm run dev--framework:nextjs,react,astro,nuxt,vue,sveltekit,angular,laravelorsymfony. 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.localfor Next.js,.envfor 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-keycreates 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. --installinstalls the dependencies afterwards; otherwise nothing is installed.--fromcopies 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
012Errors 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?