TILLARK · QUICKSTART

From a source to a proven restore.

PREVIEW

Register what you’re protecting, point it at a cross-vendor target, set a policy, take a backup, then prove it restores — the whole loop, from the CLI.

01Install

Install the CLI and log in

TillArk lives inside the one tilldev CLI, alongside pulse, shield, cache, and secrets. The CLI talks to the API over HTTPS only.

bash

# The TillArk commands ship inside the one TillDev CLI.
npm i -g @tilldev/cli        # or: pnpm add -g @tilldev/cli
tilldev login                # opens the browser; scopes the CLI to your org

02Source

Register a source

A source is a protected resource — a Postgres (incl. Neon), MySQL, Mongo, ClickHouse, Meilisearch, Redis, or an object store. Its connection string is envelope-encrypted under a per-org key on write and is never returned on read (the API exposes a has_dsn boolean, nothing more).

bash

# Register the thing you're protecting. The DSN is a secret —
# it's read from a hidden prompt (or --dsn-stdin), never bare on argv,
# and stored envelope-encrypted (never returned on read).
tilldev ark sources create \
  --name "acme-prod" \
  --type postgres \
  --provider neon \
  --residency eu \
  --with-dsn
# → source  <uuid>   dsn: encrypted

03Target

Register a cross-vendor target

A target is where backups land — S3, R2, B2, Wasabi, GCS, Azure, MinIO, or SFTP. Put it on a different vendor and region than the source, and turn on object-lock (--lock-days) so backups can’t be deleted or overwritten inside the retention window — ransomware-proofing.

bash

# Register a cross-vendor storage target with object-lock (WORM).
# Provider creds are a JSON object, also read via prompt / --creds-json-stdin.
tilldev ark targets create \
  --name "acme-backups-r2" \
  --provider r2 \
  --bucket acme-backups \
  --residency eu \
  --lock-days 30 \
  --with-creds
# → target  <uuid>   immutable: true   creds: encrypted

Secrets never touch argv

Both the source DSN and the target credentials are read from a hidden prompt (or --dsn-stdin / --creds-json-stdin), not passed as a flag value — so they never land in your shell history or the process table. They are stored envelope-encrypted and are never returned by the API.

04Policy

Set a policy

A policy ties a source to a schedule, a GFS retention plan, RPO/RTO SLOs, and a verification cadence — how often TillArk should prove the restore works.

bash

# Schedule + retention (GFS) + SLOs + how often to prove the restore.
tilldev ark policies create \
  --source <source-id> \
  --cron "0 */6 * * *" \
  --rpo 300 --rto 600 \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 12 \
  --verify-cron "0 3 * * *"
# → policy  <uuid>   cron 0 */6 * * *   rpo 300s   verify 0 3 * * *

An all-zero retention is rejected — a policy can never mean “keep nothing.”

05Back up

Run a backup

Queue a run. The agent claims it, encrypts the data client-side, streams ciphertext to the target, and reports a hybrid-signed manifest back. The control plane records the manifest — never the bytes.

bash

# Queue a backup. The agent claims the run, encrypts client-side,
# streams ciphertext to the target, and reports a SIGNED manifest back —
# no backup bytes ever transit the control plane.
tilldev ark backups run --source <source-id>
# → queued restic backup  <uuid>  (pending)

tilldev ark backups ls --source <source-id>
#  WHEN   ENGINE  STATUS     SIZE   DEDUP  SOURCE       ID
#  2m     restic  succeeded  1.4GB  3.1x   acme-prod    <uuid>

06Prove it

Verify and read the proof

This is the wedge. ark verify runs a non-destructive restore of the freshest good backup into an ephemeral, isolated sandbox, asserts integrity, and records the outcome.

bash

# A NON-destructive restore-verification: restore the freshest good
# backup into an ephemeral sandbox, assert integrity, tear down.
tilldev ark verify <backup-id>
# → queued verification restore  <uuid>  (pending)

Then read the result — and note that the same green/red flows into TillPulse:

bash

# Read the proof: kind=verify, status=passed means the backup
# actually restored and passed its integrity checks.
tilldev ark restores --backup <backup-id>
#  WHEN   KIND    STATUS   APPROVED BY   BACKUP        ID
#  1m     verify  passed   -             <backup-id>   <uuid>

# The same result is emitted to TillPulse as green/red + the observed RTO,
# and the whole chain is in the append-only audit trail:
tilldev ark audit --limit 5

Why this matters

A verified backup is promoted to verified in the catalog. The product’s promise is not “we take backups” but “your last N restores all passed, here is the proof” — and that proof is a monitored TillPulse board.

07Next

What's next

Backups & restore-verification — real restores (four-eyes gated), RPO/RTO tiers, and retention in depth.
Failover — promote a replica safely with fencing and quorum; fail back without losing writes.
Architecture — how the control plane, agent, and manifest fit together.
CLI reference — every command and flag.