Cauldron

Cauldron is the Copella deployment CLI. It uploads projects over SSH/SFTP or FTP, runs repeatable deployment recipes, creates backups, and publishes immutable releases to the shared Copella Registry.

Install

Cauldron requires Node.js 20 or newer.

npm install -g @cpltech/cauldron
cauldron --version

When a newer npm release is available, interactive commands show a short update suggestion after they finish. Cauldron checks at most once every 24 hours, ignores network failures, and never updates itself automatically. Set CAULDRON_NO_UPDATE_CHECK=1 to disable this check.

To build this repository instead:

pnpm install
pnpm run build
node dist/index.js --help

Start here if Cauldron is new to you

You do not need to write YAML or remember every option for the first deployment:

cauldron guide
cauldron login
cauldron server add
cd C:\path\to\project
cauldron init
cauldron plan .

server add explains each connection choice and verifies it. init asks where and how the project should be deployed, then creates and validates cauldron.yml. plan shows the recipe without changing the server.

Short guides are always available offline:

cauldron guide server
cauldron guide recipe
cauldron guide backups
cauldron guide releases
cauldron guide merge

First deployment

1. Sign in

cauldron login

Cauldron sends an approval request to Telegram and waits for approval. The resulting token has the cauldron:access scope and is stored locally in ~/.cauldron/config.json. Never copy or print this file: it may also contain server passwords and SSH key passphrases.

2. Add a server

cauldron server add
cauldron server list
cauldron server test app

The wizard asks for SSH/SFTP or FTP connection details and verifies the connection before saving it. For a server reached through another SSH machine, add the jump host first and select it as the connection route when adding the destination.

FTP is upload-only and unencrypted. It cannot run backups, remote commands, or service operations. Prefer SSH/SFTP.

3. Create cauldron.yml

For a new project, use the wizard:

cd C:\path\to\project
cauldron init

Choose either one-server deployment or a stage/production release flow. The wizard can add backup, upload, and service restart steps in their safe order.

For advanced manual configuration, create this file in the project root:

name: example
server: app
target: /opt/example
compressionLevel: 9
retention:
  backups: 5
  releases: 10
  cache: 3
  trashDays: 7
steps:
  - type: backup
    source: /opt/example
  - type: upload
    source: .
    target: /opt/example
  - type: service
    manager: systemd
    name: example.service
    action: restart

Normal steps run in order. This recipe first creates a recoverable archive, uploads the project, and then restarts the service.

compressionLevel accepts 1 through 9; new release and backup archives default to maximum gzip compression (9). Retention values are configurable per project. Defaults keep 5 backups, 10 Registry releases, 3 local cached releases, and recoverable Registry trash for 7 days. The currently promoted release of every environment is always protected from Registry rotation.

Cauldron storage is separated under one root:

~/.cauldron/
├── backups/   # remote backup archives
└── releases/  # local release cache

Old .cauldron-backups directories are not migrated or deleted automatically.

4. Inspect and deploy

cauldron plan .
cauldron deploy .

plan is read-only. deploy asks for confirmation before changing production. Use --yes only after reviewing the plan in an approved non-interactive workflow.

Without cauldron.yml, Cauldron uploads the selected folder to a selected server. With a recipe, it executes the declared steps.

Shared immutable releases

The Copella Registry is the source of truth for release artifacts, SHA-256 hashes, projects, environments, and promotion history. ~/.cauldron/releases is only a local cache.

The simplest workflow creates and publishes in one command:

cauldron release publish . --name example --version 1.2.0

To inspect an artifact before publishing, use two steps:

cauldron release create . --name example --version 1.2.0
cauldron release publish [email protected]

Both -v 1.2.0 and --version 1.2.0 are supported by release create and source-based release publish.

Useful Registry commands:

cauldron release list
cauldron release list example
cauldron release pull [email protected]
cauldron release deploy [email protected] --yes
cauldron release cache list

Remove only the local cached copy without affecting the team Registry:

cauldron release cache remove [email protected]
cauldron release cache prune example --keep 3

Remove a release from the shared Registry:

cauldron release remove [email protected]

Registry removal moves the artifact into recoverable server trash and writes a permanent tombstone. The deleted name@version can never be published again. Both removal commands ask for confirmation; approved automation may use --yes.

Publishing the same name@version twice is rejected even when the bytes are identical. Use a new version for every changed artifact. pull, deploy, and promote download the Registry artifact and verify SHA-256 before extracting it.

Registry releases cannot be merged with each other because they are immutable deployment snapshots. Merge branches or changes in the source-control working tree, test the result, and publish it as a new version. Run cauldron guide merge for the exact sequence.

Release archives exclude .git, .cauldron, node_modules, .env*, and logs by default. Add project-specific patterns to .cauldronignore.

Environments and promotion

Declare environments in the same cauldron.yml that is included in the release:

name: example
environments:
  stage:
    server: stage
    target: /opt/example
  production:
    server: production
    target: /opt/example
steps:
  - type: upload
    source: .
  - type: service
    manager: systemd
    name: example.service
    action: restart

Promote the exact published artifact without rebuilding it:

cauldron release promote [email protected] --to stage --yes
cauldron release promote [email protected] --to production --yes

A successful promotion is recorded centrally. A dry run verifies and plans the release without recording a promotion:

cauldron release promote [email protected] --to production --dry-run

Recipe reference

Upload

- type: upload
  source: .
  server: app
  target: /opt/example

SFTP compares remote files concurrently and uploads only changes. The step-level server and target override project defaults.

Local command

- type: local-command
  executable: node
  args: [scripts/build.mjs]

Use an executable and an argument array, not a shell command string. On Windows, .cmd and .bat wrappers are supported.

Remote command

- type: remote-command
  executable: node
  args: [/opt/example/scripts/migrate.mjs]

Service

- type: service
  manager: systemd
  name: example.service
  action: restart

manager may be systemd or pm2; action may be start, stop, or restart.

Backup

- type: backup
  source: /opt/example
  destination: /home/deploy/.cauldron/backups
  keep: 5
  compressionLevel: 9

Parallel steps

Use parallel only for independent operations:

- type: parallel
  steps:
    - type: service
      server: api
      manager: systemd
      name: api.service
      action: restart
    - type: service
      server: worker
      manager: systemd
      name: worker.service
      action: restart

Standalone backups

In an interactive terminal, options may be omitted. Cauldron asks you to select the SSH server and enter the required paths:

cauldron backup create
cauldron backup list
cauldron backup restore
cauldron backup prune

For scripts and CI, provide explicit options:

cauldron backup create --server app --source /opt/example --label before-v2 --keep 5 --compression-level 9
cauldron backup list --server app
cauldron backup prune --server app --keep 5
cauldron backup restore --server app --archive /home/deploy/.cauldron/backups/example-before-v2-<timestamp>.tar.gz --target /opt/example
cauldron backup remove --server app --archive /home/deploy/.cauldron/backups/example-before-v2-<timestamp>.tar.gz

Restore keeps the previous target beside the restored directory with a timestamped .cauldron-previous-... suffix.

Templates and diagnostics

cauldron template save node-service .
cauldron template list
cauldron template apply node-service .
cauldron template remove node-service

cauldron history 20
cauldron doctor
cauldron config

doctor checks the current Copella Login session and configured server connections without deploying anything.

Project structure

• src/index.ts assembles the CLI and registers command groups.
• src/commands/ contains command handlers grouped by domain.
• src/release.ts owns local archive creation, cache storage, extraction, and SHA-256 verification.
• src/registry.ts is the authenticated client for the central Copella Registry.
• src/project-config.ts validates cauldron.yml.
• src/pipeline.ts executes recipe steps.
• src/ssh.ts and src/ftp.ts implement transports.