CLI Reference

18 commands covering everything from init to disaster recovery. All scriptable.

Quick Overview

The Ginkgo CLI talks to the local HTTP API (default 127.0.0.1:9275) of the background daemon. Every command can run standalone or be chained into automation scripts. The token is auto-generated on first start and saved to ~/.ginkgo-backup/config.json.

Global Flags

All commands share these flags, settable via CLI or environment variables:

Flag	Env Variable	Default	Description
`--token`	`GINKGO_TOKEN`	—	API auth token (auto-generated on first start)
`--port`	`GINKGO_PORT`	9275	API server port
`--host`	`—`	127.0.0.1	API server host
`--tls`	`GINKGO_TLS=1`	auto	Use HTTPS (auto-detected if unset; required for TLS-enabled servers)

First-Time Setup

Shell

# Save token to config file (no need to specify each time)
ginkgo config save --token <token> --port 9275

# Show current config
ginkgo config show

Commands by Group

Init & Status

ginkgo init [path]Initialize a backup source

flags: --schedule (manual/hourly/daily/weekly, default: daily)

ginkgo sourcesList all backup sources

ginkgo statusSystem status overview (running tasks, disk, health)

ginkgo versionPrint version information

ginkgo config saveSave token/port to config file

flags: --token, --port

ginkgo config showShow current configuration

Backup & Progress

ginkgo backup --source <id>Trigger a backup (async, fire-and-forget)

flags: --source (0 = all), --message, --wait

ginkgo checkpoint --source <id>Trigger a backup and block until done (script-friendly)

flags: --source (0 = all), --message, --timeout (default 600s)

ginkgo progressShow current backup progress (files, bytes, stage)

Staging (Instant Protection)

ginkgo staging push --source <id>Push changed files to COW staging area (fire-and-forget)

flags: --source (required), --paths, --files, --message

ginkgo staging push-ai --source <id>Push files marked as AI-generated (forces note_source=ai)

flags: --source (required), --paths, --files, --message

Snapshots & History

ginkgo snapshots --source <id>List snapshots

flags: --source, --limit (default 20)

ginkgo history <file_path>View file version history

flags: --source (required); file_path is a positional arg

ginkgo diff --source <id>Diff between the last two snapshots

flags: --source (required)

Restore & Export

ginkgo restore <file_path>Restore a file from a snapshot

flags: --source, --snapshot (both required), --dest; file_path is positional

ginkgo export --source <id>Export a snapshot as a zip/tar archive

flags: --source (required), --snapshot, --output (required), --format (zip/tar, default zip)

Verify & Mount

ginkgo verify --source <id>Verify backup integrity (quick by default)

flags: --source (required), --deep, --repair, --repo

ginkgo mount --source <id>Mount a snapshot as a local drive

flags: --source (required), --mount-point (required), --snapshot (default: latest)

Retention

ginkgo retention --source <id>Apply GFS retention policy to a source

flags: --source (required), --policy (keep_all/smart/custom, default smart), --custom, --dry-run

AI Notes

ginkgo generate-note --source <id>Generate an AI-powered note from the latest snapshot data

flags: --source (required)

Typical Workflows

First-time setup + daily backup

Shell

# 1. Initialize a backup source (daily schedule)
ginkgo init /home/user/documents --schedule daily

# 2. Trigger the first backup and wait
ginkgo backup --source 1 --wait

# 3. List snapshots
ginkgo snapshots --source 1

Recover a deleted file

Shell

# 1. View file version history
ginkgo history /docs/report.pdf --source 1

# 2. Restore to a specific snapshot
ginkgo restore /docs/report.pdf \
  --source 1 \
  --snapshot 1715001600000 \
  --dest /tmp/restore

AI coding safety loop

Shell

# 1. Checkpoint before a risky refactor (blocks until done)
ginkgo checkpoint --source 1 --message "pre refactor: auth module"

# 2. AI performs the refactor (external)

# 3. Instantly protect changed files via staging
ginkgo staging push --source 1 --paths "src/auth.go,src/session.go" --message "feat: rewrite auth"

# 4. Diff against the last snapshot
ginkgo diff --source 1

Server/NAS Headless Deployment

Shell

# 1. Build the headless server
go build -o ginkgo-server ./cmd/ginkgo-server

# 2. Start in background (headless auto-enables TLS)
./ginkgo-server --tls-auto &

# 3. Save the token from the log
ginkgo config save --token <token-from-log> --port 9275

# 4. Initialize multiple sources
ginkgo init /data/projects --schedule daily
ginkgo init /data/photos --schedule weekly

CLI Reference

Quick Overview

Global Flags

First-Time Setup

Commands by Group

Init & Status

Backup & Progress

Staging (Instant Protection)

Snapshots & History

Restore & Export

Verify & Mount

Retention

AI Notes

Typical Workflows

First-time setup + daily backup

Recover a deleted file

AI coding safety loop

Server/NAS Headless Deployment

See Also