CLI utility for full backup and restore of n8n workflows, credentials, and tags via REST API
A modern, type-safe CLI tool built with Bun and TypeScript that enables comprehensive backup and restore operations for n8n automation workflows. All backups are versioned and stored in PocketBase with full audit trails.
- π Full Backup & Restore - Complete snapshot of workflows, credentials, and tags
- π¦ PocketBase Storage - Versioned backups with strict audit trails
- π Profile Management - Multiple n8n instances with encrypted credentials
- π Detailed Reporting - Per-object status tracking and comprehensive metrics
- β Version Validation - Strict n8n version compatibility checks
- π‘οΈ Error Resilience - Never fails mid-operation, always reports issues
- π§ͺ Test-Driven Development - 80%+ test coverage with TDD methodology
- Bun >= 1.3 (install)
- n8n instance with API access
- PocketBase for backup storage
# Install globally via bun
bun install -g @gander-tools/n8n-backup
# Or use with bunx (no installation required)
bunx @gander-tools/n8n-backup# Backup workflows from default profile
n8n-backup backup
# Restore from specific version
n8n-backup restore <version_id>
# Sync between profiles
n8n-backup sync --source prod --target staging
# List available profiles
n8n-backup profiles listCreates a full snapshot of workflows, credentials, and tags from n8n via REST API.
Options:
--profile <name>- Profile to use (default: default profile)--output <dir>- Output directory for reports--verbose- Enable detailed logging
Output:
- New version record in PocketBase
- Per-object reports (workflow_report, credential_report, tag_report)
- Audit record with full operation metadata
Restores data from a specific backup version to target n8n instance.
Requirements:
- Exact minor version match between source and target n8n
- If version mismatch: operation aborts with no changes
Options:
--profile <name>- Target profile--dry-run- Preview changes without applying
Behavior:
- Always runs in ignore-errors mode
- Skipped/errored objects are reported
- Never fails hard mid-operation
Performs backup from source and restore to target as a single operation.
n8n-backup sync --source prod --target staging --backupOptions:
--source <profile>- Source profile (authoritative)--target <profile>- Target profile--backup- Create backup before sync
Manage n8n instance profiles.
# Add new profile
n8n-backup profiles add --name prod --url https://n8n.example.com --api-key KEY
# List profiles
n8n-backup profiles list
# Set default profile
n8n-backup profiles set-default prodBuilt with clean, layered architecture following TDD principles:
src/
βββ commands/ # CLI entry points (backup, restore, sync)
βββ services/ # Business logic (api-client, pocketbase-client)
βββ types/ # TypeScript definitions
βββ utils/ # Helper functions
tests/
βββ unit/ # Fast, isolated tests
βββ integration/ # Component interaction tests (Docker)
This project strictly follows TDD with the Red-Green-Refactor cycle:
- π΄ RED - Write a failing test
- π’ GREEN - Write minimal code to pass
- π΅ REFACTOR - Improve and optimize
Coverage Requirements:
- Minimum: 80% (enforced in CI/CD)
- Target: 90%+
- All paths: happy, sad, and edge cases
# Run tests in TDD watch mode
bun test --watch
# Run with coverage report
bun test --coverageSee tests/README.md for detailed testing guide.
# Clone repository
git clone https://github.com/gander-tools/n8n-backup.git
cd n8n-backup
# Install dependencies
bun install
# Install git hooks (Lefthook)
bun run prepare# Run in development mode
bun run dev
# Run tests (TDD mode)
bun test --watch
# Lint and format
bun run lint
bun run format
# Type checking
bun run typecheck
# Run full CI pipeline locally
bun run ci- Linter/Formatter: Biome (not ESLint/Prettier)
- Git Hooks: Lefthook (enforces format, lint, tests)
- CI/CD: GitHub Actions (lint, format, test, build)
All backups stored in PocketBase with the following structure:
- versions - Backup metadata, metrics, timestamps
- workflows - Workflow data + per-object reports
- credentials - Encrypted credentials + reports
- tags - Tag data + reports
- audits - Complete audit trail
- profiles - n8n instance configurations
Each backup creates a new version with all data linked by version_id.
This tool does not include built-in security beyond PocketBase encryption. You are fully responsible for:
- Securely storing configuration and API keys
- PocketBase access control and permissions
- Preventing unauthorized access to backups
- Data protection compliance (GDPR, etc.)
API keys are stored encrypted in PocketBase, but securing the PocketBase instance itself is your responsibility.
- Runtime: Bun >= 1.3
- Language: TypeScript >= 5.9
- Linter/Formatter: Biome
- Git Hooks: Lefthook
- Testing: Bun test framework
- Storage: PocketBase
Contributions are welcome! Please see CONTRIBUTING.md for details.
Development Requirements:
- Follow TDD methodology (write tests first!)
- Maintain 80%+ test coverage
- Use Biome for linting/formatting
- Follow conventional commits
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Copyright (C) 2025 Adam GΔ sowski
- Repository: https://github.com/gander-tools/n8n-backup
- Issues: https://github.com/gander-tools/n8n-backup/issues
- NPM Package: https://www.npmjs.com/package/@gander-tools/n8n-backup
- Author: Adam GΔ sowski (@gander)
- Organization: Gander Tools
Status: Project in planning phase. See ROADMAP.md for complete feature list.
- MVP: Core backup and restore functionality
- Profile management system
- Sync command with merge strategies
- Selective backup (filter by ID, tags, date)
- Differential backup (track changes)
- Advanced output formats (JSON, CI mode)
- Retention policies and cleanup command
- Encryption and signing (GPG/KMS)
For detailed implementation plan, see the complete roadmap.
If you encounter any issues or have questions:
- Check the documentation
- Search existing issues
- Open a new issue
Built with β€οΈ using Test-Driven Development