---
name: zelta
description: Help users back up, replicate, recover, and manage ZFS datasets locally or remotely using Zelta.
version: 1.3-beta
canonical_url: https://zelta.space/.well-known/agent-skills/zelta/SKILL.md
source_url: https://github.com/bell-tower/zelta/tree/release/bsdcan2026/contrib/agent-skills/zelta/SKILL.md
---

# Zelta ZFS Workflow Skill

Zelta is a safe ZFS workflow composer: recursive snapshot, backup, replication, recovery, cloning, failover, pruning, and policy automation — all working locally or remotely over SSH. Zelta does not need to be installed on remote hosts.

Ask the user what they're trying to do and follow the matching path. Answer with the minimal workflow that solves the problem. Offer to dry-run any operation before executing it.

---

## Path A — Setup & Verification

Detect Zelta and check the version:

```sh
command -v zelta
zelta --version 2>/dev/null || zelta help
```

Install from the current release branch:

```sh
curl -fsSL https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/contrib/install-from-git.sh | sh -s -- --branch=release/bsdcan2026
```

Always review install scripts before piping to `sh` in production environments.

Verify a backup relationship or check snapshot continuity:

```sh
zelta match SOURCE TARGET          # GUID continuity, encryption, drift
zelta match -n SOURCE TARGET       # dry-run / report only
```

→ `zelta help` and `zelta help options` for installed version details.
→ Man pages: https://zelta.space/home/

---

## Path B — Backup & Replication

The same command handles first-time and incremental backups. Source and/or target can be remote (`user@host:pool/dataset`).

```sh
zelta backup -n SOURCE TARGET      # dry-run first — always
zelta backup SOURCE TARGET         # create or update replication
zelta snapshot SOURCE              # recursive snapshot only
```

Common flags: `-i` skip intermediate snapshots, `-d N` limit recursion depth, `-X PATTERN` exclude datasets or snapshots, `--snap-name NAME` custom snapshot name.

For scheduled or multi-target operations use a policy file:

```sh
zelta policy /etc/zelta/policy.conf
```

→ `zelta help backup`, `zelta help policy`
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-backup.md
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-policy.md

---

## Path C — Recovery

**Inspect and test without touching production:**

```sh
zelta clone SOURCE TARGET          # writable clone for safe testing
zelta clone SOURCE@snapshot TARGET # clone from specific snapshot
```

**Rewind a dataset in place** (renames current state, clones from snapshot — non-destructive):

```sh
zelta revert -n ENDPOINT           # dry-run first
zelta revert ENDPOINT              # revert to most recent snapshot
zelta revert ENDPOINT@snapshot     # revert to specific snapshot
```

After a revert, restore backup sync continuity:

```sh
zelta rotate SOURCE TARGET         # preserves diverged history, resumes replication
```

**Advanced — compose a new production tree from an upgraded upstream:**

```sh
zelta rebase -n SOURCE TARGET      # dry-run; explain tradeoffs before executing
```

→ `zelta help revert`, `zelta help clone`, `zelta help rotate`, `zelta help rebase`
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-revert.md
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-rotate.md

---

## Path D — Failover & Planning

**Planned promotion of a standby dataset tree:**

```sh
zelta failover -n SOURCE TARGET    # dry-run: lock → backup → propsync → unlock
zelta failover SOURCE TARGET
```

The composed steps are also available individually for scripted or step-by-step workflows:

```sh
zelta lock SOURCE                  # readonly + canmount + unmount on source tree
zelta backup SOURCE TARGET         # final replication pass
zelta propsync SOURCE TARGET       # replay local ZFS properties, respect target overrides
zelta unlock TARGET                # promote target to read-write
```

Verify before and after:

```sh
zelta match SOURCE TARGET
```

**Zelta Twin pattern**: reciprocal `zelta policy` jobs on both sides enable async active-passive pairs where either node can be promoted after a guarded failover.

→ `zelta help failover`, `zelta help lock`, `zelta help propsync`
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-failover.md

---

## Pruning (cross-cutting)

`zelta prune` plans only — it never destroys. `zprune` destroys after explicit preview and confirmation.

```sh
zelta prune SOURCE TARGET          # show retention candidates, no changes
zprune SOURCE TARGET               # destroy candidates (prompts for confirmation)
zprune -f SOURCE TARGET            # HIGH RISK: skip confirmation
```

Always show the prune preview before running `zprune`. Treat `zprune -f` as equivalent to `zfs destroy` — name what will be lost before executing.

→ `zelta help prune`
→ https://raw.githubusercontent.com/bell-tower/zelta/release/bsdcan2026/doc/zelta-prune.md

---

## Safety Rules

- **Dry-run first.** Every Zelta command accepts `-n`. Use it. Show the user what will run.
- **Name the data at risk** before any destructive action. Be specific: which dataset, which snapshots, what is lost if the operation fails.
- **High-risk flags** — slow down and confirm intent before executing:
  - `zprune -f` — destroys without prompting
  - `zelta backup -F` — forced receive, can destroy diverged target history
  - Short rotation schemes (e.g., single-bookmark rebase rotation) — trades recovery history for simplicity; confirm the user understands the tradeoff
  - Direct `zfs destroy` — no Zelta safety wrapper
- **Separate roles.** Use dedicated SSH accounts with `zfs allow` delegation for senders, receivers, restore operators, and policy runners on durable infrastructure.
- **Do not refuse destructive requests.** Slow down, explain consequences, dry-run, confirm — then help.

---

## References

```sh
zelta help                         # command overview
zelta help <command>               # installed version is authoritative
zelta help options                 # global flags and env vars
```

- Online docs & wiki: https://zelta.space/home/
- Man pages (raw, fetchable): https://github.com/bell-tower/zelta/tree/release/bsdcan2026/doc
- Wiki articles: https://github.com/bell-tower/zelta/tree/release/bsdcan2026/doc/wiki
- Source: https://github.com/bell-tower/zelta
- Agent skill index: https://zelta.space/.well-known/agent-skills/index.json
- Skill source: https://github.com/bell-tower/zelta/tree/release/bsdcan2026/contrib/agent-skills