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 dev and production environments in under 10 minutes.

Install

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

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

Verify:

Terminal window
chiral --version

Create a project

Chiral keeps state in a managed project directory under ~/.local/share/chiral/projects/. Run init once per n8n deployment you want to manage:

Terminal window
chiral init my-n8n

Output:

  my-n8n


  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/config.example.json
  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/.gitignore
  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/credentials.json
  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/audit.jsonl
  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/locks/
  ✓  ~/.local/share/chiral/projects/my-n8n/.chiral/snapshots/


  ✓  Git initialized → ~/.local/share/chiral/projects/my-n8n


  Next: chiral environment add dev

The free tier allows one project. The Team tier lifts this limit.

Add your environments

Add each n8n instance you want to manage. Chiral prompts for the URL and API key, then tests the connection before saving:

Terminal window
chiral environment add dev
  Environment name: dev
  n8n URL: https://dev.n8n.example.com
  API key: ••••••••


  ✓ Connected to dev (12 workflows found)
  ✓ Environment saved

Repeat for production:

Terminal window
chiral environment add prod

Generate an API key in n8n under Settings → API → Create API key. Chiral needs read/write access to workflows and read access to credentials.

Adopt your environments

adopt connects to each environment, takes a full workflow snapshot, and computes content fingerprints. Run it once per environment before your first diff:

Terminal window
chiral adopt --env dev
chiral adopt --env prod

Output for each:

Connecting to dev (https://dev.n8n.example.com)...
✓ Discovered 12 workflows
✓ Discovered 4 credentials (names only — secrets are never read)
✓ Snapshot saved    → .chiral/snapshots/20260530T120000Z-a3f2b9c1/
✓ Fingerprints saved → .chiral/fingerprints.json  (12 workflows)

Run your first diff

Terminal window
chiral diff --source dev --target prod

Chiral compares content fingerprints between environments. Version ID noise is filtered — if chiral diff reports a change, the workflow content actually changed.

Comparing dev → prod


  + New Workflow             (will be created — wrong name? run: chiral workflow map)
  ~ Invoice Processor        (modified — content differs)
  - Deprecated Webhook       (in prod, not in dev)


1 added, 1 modified, 1 removed.
Run 'chiral push --source dev --target prod --dry-run' to preview.

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

What’s next

  • chiral push --source dev --target prod --dry-run — preview a promotion before it touches anything
  • chiral push --source dev --target prod — promote workflows from dev to prod
  • chiral pull --env prod — refresh your local snapshot after changes in n8n
  • Commands reference — full reference for every command and flag