Umbraco Compose CLI

[!WARNING] Experimental software: This project is currently experimental and not yet considered production-hardened.
Use caution when running against real or sensitive data, and validate plans carefully before applying changes.

A CLI for managing Umbraco Compose environments with an IaC-style workflow.

It helps teams:

• scaffold and organize local Compose project files
• validate local configuration before API calls
• preview remote changes with plan
• apply changes safely in CI/CD
• keep environment identity stable across renames

Core Workflow

1. Create or clone a Compose project.
2. Edit local files in source control.
3. Run validate and plan.
4. Run apply in a guarded pipeline.

Quick Start

Start New

node dist/index.js init --dir ./compose --project <project-alias> --env dev
cd ./compose
node ../dist/index.js validate --strict
node ../dist/index.js plan

Start From Existing Remote

node dist/index.js clone --dir ./compose --project <project-alias> --allEnvs
cd ./compose
node ../dist/index.js validate --strict
node ../dist/index.js plan

If you cloned a subset of environments and later need another:

node ../dist/index.js env add-remote <env-alias> --pull
# or
node ../dist/index.js pull --env <env-alias> --adoptMissing

Authentication

Commands that call the management API require OAuth client credentials.

Required:

• COMPOSE_MGMT_CLIENT_ID
• COMPOSE_MGMT_CLIENT_SECRET

Optional:

• COMPOSE_MGMT_SCOPE
• COMPOSE_MGMT_AUDIENCE

You can also pass --clientId, --clientSecret, --scope, and --audience on commands that support them.

Command Overview

• compose init
• compose clone
• compose generate <entity> <alias>
• compose validate
• compose pull
• compose status
• compose plan
• compose apply
• compose env rename <from> <to>
• compose env add <alias>
• compose env list-remote
• compose env add-remote <alias>

Directory defaults:

• Local-state commands default --dir to current directory (.).
• Bootstrap commands (init, clone) default --dir to ./compose.
• clone and pull default --env to production when omitted.
• env rename moves ./env/<from> to ./env/<to> by default (--no-moveDir to opt out).

CI/CD Model

• PR CI: build, test, validate, plan
• Deploy workflow: guarded apply (manual/protected branch + environment approvals)

See:

• docs/commands.md
• docs/workflow.md
• docs/ci.md
• docs/testing.md
• docs/release-v1-checklist.md