projects · varn v0.4.0 · cli manual

CLI Reference.

Complete command-line manual, flags, ignore syntax, JSON output schemas, and safety model for Varn. Built for developers and autonomous agent loops.

← varn overview·install·commands·json output·source

Installation

linux & macos:

[bash]

curl -fsSL https://raw.githubusercontent.com/flawme/varn/master/install.sh | sh

windows powershell:

[powershell]

iwr -useb https://raw.githubusercontent.com/flawme/varn/master/install.ps1 | iex

rust cargo:

[bash]

cargo install --git https://github.com/flawme/varn.git

Quick Start

[bash]· Standard checkpoint and rollback loop

varn init
varn checkpoint "before changes"

# ... edits happen or an autonomous agent runs ...
varn diff <checkpoint-id>
varn restore <checkpoint-id>

# unwanted restore? undo instantly:
varn undo

Commands Reference

varn init[path] [--gitignore]

Initialize a .varn repository. In Git projects, automatically adds an ignore guard to keep checkpoint objects out of git stages.

varn init              # initialize in current directory
varn init /path/to/dir # initialize in a specific directory
varn init --gitignore  # also append .varn/ to root .gitignore

varn checkpoint<description>

Capture the complete filesystem state: unique 12-char SHA-256 ID, timestamp, description, and deduplicated object store. Checkpoint writes are crash-durable (fsync on publish).

varn checkpoint "before refactor"

varn list

Display all available checkpoints with creation timestamps, commit messages, and entry counts.

varn list

varn diff<id> [id]

Compare current disk against a checkpoint, or compare two historical checkpoints directly without scanning disk.

varn diff a91f                       # compare checkpoint vs current disk state
varn diff a91f b72c                   # compare two historical checkpoints directly

varn restore<id> [--yes] [--no-safety]

Restore files to a checkpoint state through a 4-phase atomic pipeline. Automatically captures a safety checkpoint before applying changes.

varn restore a91f                          # interactive restore
varn restore a91f --yes                    # skip confirmation prompts
varn restore a91f --yes --no-safety        # skip safety checkpoint creation

varn undo[--yes] [--no-safety]

Revert the last restore operation. Restores the pre-restore state through the complete 4-phase pipeline and creates a new safety checkpoint.

varn undo              # interactive undo of the last restore
varn undo --yes        # non-interactive undo

varn delete<id> [--keep-last N] [--older-than AGE] [--safety-only]

Remove checkpoint references by ID or retention rule. Unreferenced objects can then be reclaimed with gc.

varn delete a91f                        # delete specific checkpoint
varn delete a91f --yes                  # delete without confirmation
varn delete --keep-last 10              # retain 10 newest, delete older
varn delete --older-than 30d            # delete checkpoints older than 30 days
varn delete --safety-only --keep-last 3 # prune older safety checkpoints

varn gc[--dry-run]

Delete unreferenced content-addressed objects from the store to reclaim disk space.

varn gc             # delete unreferenced objects from the store
varn gc --dry-run   # preview objects and reclaimed space

varn migrate[--dry-run]

Inspect or apply pending storage format migrations.

varn migrate             # apply pending storage migrations
varn migrate --dry-run   # inspect if migrations are needed

varn --json<command>

Emit structured machine-readable JSON output for automated AI agents and scripts.

varn --json checkpoint "automated save"
varn --json diff a91f
varn --json restore a91f --yes
varn --json delete a91f --yes

Ignore Patterns (.varnignore)

Place a .varnignore file in your project root to exclude build artifacts, large binaries, or temporary directories using standard gitignore syntax.

[ini]

# ignore temporary build directories
target/
build/
dist/

# ignore log files
*.log

# ignore local environment files
.env
.env.*

JSON Output for Automated Agents

Use the global --json flag with any command to produce machine-readable output for agent loops.

checkpoint response:

[json]

{
  "status": "ok",
  "checkpoint": "a91f3c2b4d5e",
  "description": "automated save",
  "entries": 12,
  "saved": true,
  "warnings": []
}

restore response:

[json]

{
  "status": "ok",
  "checkpoint": "a91f3c2b4d5e",
  "safety_checkpoint": "b72c1a3e5f7d",
  "files_written": 3,
  "dirs_created": 1,
  "symlinks_created": 0,
  "deleted": 2,
  "verified": true,
  "warnings": []
}

← varn overview home