Skip to content
Chiral

Getting Started

Chiral is a CLI for self-hosted n8n CE teams. This guide takes you from zero to a live diff of your staging and production environments in under 10 minutes.

Install

Terminal window
sh -c "$(curl -sSfL https://chiral.sh/install)"

Chiral installs a single binary to /usr/local/bin/chiral. No Node.js, no Python, no runtime dependency.

Verify:

Terminal window
chiral --version

Initialize your project

Navigate to a git repository — or create one. Chiral uses git to store diffs and audit history.

Terminal window
cd your-repo
chiral init

chiral init prompts for:

  1. n8n instance URL — e.g. https://n8n.yourdomain.com
  2. API key — generate one in n8n under Settings → API → Create API key

This creates a .chiral/ directory with your config. The config does not store your API key in plaintext — it stores a reference that you confirm at each write operation.

Adopt your environments

Tell Chiral which n8n instances you’re working with:

Terminal window
chiral adopt --env staging
chiral adopt --env production

Each adopt command:

  • Connects to the instance URL you configured for that environment
  • Takes a snapshot of all workflow content fingerprints
  • Stores the snapshot locally (not pushed to n8n)

Run your first diff

Terminal window
chiral diff --from staging --to production

Chiral compares the content fingerprints of each workflow between environments. You’ll see output like:

  Comparing environments: staging → production
  Content fingerprints verified. No version ID noise.


  ─── MODIFIED (2) ─────────────────────────────────────


  ✎  Invoice Processor v2
     ↳ Node "Set Amount" — expression changed
     ↳ Webhook URL differs (expected — credential remap)


  ✎  Client Onboarding
     ↳ Node "Send Confirmation" — subject line updated


  ─── UNCHANGED (14 workflows) ──────────────────────────


  Run `chiral push --dry-run` to preview the promotion.

That’s it. You now have a full diff of your environments.

What’s next