Push & Pull via Cloud

Clonit gives you two ways to move snapshots between machines. Both use the same push and pull commands — the only difference is where the bytes live and whose credentials are used.

• Local storage profile (the default): Clonit uploads to a bucket you own, using S3/R2 credentials you configured on this machine.
• Clonit Cloud (--cloud): Clonit asks your organization’s cloud to hand it a short-lived presigned URL, then uploads to your org’s managed storage. You never put S3 credentials on this machine.

You can mix and match: a laptop with no S3 keys can still pull a teammate’s snapshot with --cloud, while a CI runner with its own bucket can push to a local storage profile.

Pathway 1: Local storage profile (default)

This is the standalone path. It works with no cloud connection at all — you just need a storage profile linked to the target.

# Push the latest snapshot to your bucket
clonit push mydb

# Push a specific snapshot by index
clonit push mydb 0

# Pull the latest snapshot back down
clonit pull mydb

# Pull a specific snapshot by index
clonit pull mydb 0

With this pathway, push and pull read the credentials, bucket, region, and prefix from the storage profile attached to the target. Snapshots are referenced by their index in clonit snapshots <target> — there is no cloud catalog involved.

Note

The default pathway requires the target to have a storage profile linked. See Cloud Storage to create one with clonit storage-profile add and attach it with clonit targets update.

Pathway 2: Clonit Cloud presigned storage (--cloud)

The --cloud flag opts into your organization’s managed storage. Instead of using local S3 credentials, Clonit:

1. Authenticates with Clonit Cloud (your login session or an API key).
2. Requests a short-lived presigned URL for the snapshot.
3. Uploads or downloads the file directly to/from your org’s managed storage, then confirms the transfer (size + checksum).

The payoff: no S3 credentials need to live on this machine. A new teammate can clonit login, then immediately pull a shared snapshot without ever seeing a bucket name or access key.

# Push the latest snapshot through Clonit Cloud
clonit push mydb --cloud

# Pull a snapshot through Clonit Cloud (snapshot ID required — see below)
clonit pull mydb --cloud --snapshot-id <id>

Caution

--cloud requires a configured cloud connection. Set cloud.url and sign in with clonit login, or set an API key for headless use. See Connect Your Agent. Without cloud configuration, --cloud has nothing to talk to and the command will error.

push flags

From clonit push --help:

Push a snapshot to remote storage (local storage profile by default)

Usage:
  clonit push <target> [snapshot_index] [flags]

Flags:
      --cloud       use Clonit Cloud presigned URLs instead of local storage profile (requires cloud config)
      --no-verify   skip checksum verification

Flag	Description
--cloud	Upload through Clonit Cloud’s managed storage via a presigned URL instead of your local storage profile. Requires cloud config.
--no-verify	Skip the SHA-256 checksum verification performed after upload.

The positional snapshot_index selects which snapshot to push; omit it to push the latest. Run clonit snapshots <target> to see indices.

pull flags

From clonit pull --help:

Pull a snapshot from remote storage (local storage profile by default)

Usage:
  clonit pull <target> [snapshot_index] [flags]

Flags:
      --cloud                use Clonit Cloud presigned URLs instead of local storage profile (requires cloud config)
      --no-verify            skip checksum verification
      --snapshot-id string   cloud snapshot ID to download (required with --cloud)
      --type string          snapshot type to pull (original, sanitized)

Flag	Description
--cloud	Download through Clonit Cloud’s managed storage via a presigned URL. Requires cloud config.
--snapshot-id	The cloud snapshot ID to download. Required when using --cloud.
--type	Which snapshot variant to pull: original or sanitized. Useful when a target keeps separate originals and sanitized copies.
--no-verify	Skip the SHA-256 checksum verification performed after download.

Local pull uses an index; cloud pull uses a snapshot ID

This is the key difference to remember:

• Local pathway: snapshots are addressed by index — a small number that is only meaningful on this machine.

  clonit pull mydb 0

• Cloud pathway: snapshots are addressed by a cloud snapshot ID — a stable identifier shared across your whole organization, so the same snapshot resolves the same way on every machine.

  clonit pull mydb --cloud --snapshot-id <id>

Tip

To find a cloud snapshot ID, browse your organization’s shared snapshots in the web UI’s Cloud section (clonit serve) or list them from the CLI with clonit cloud snapshots. Copy the ID of the snapshot you want and pass it to --snapshot-id.

Choosing a pathway

	Local storage profile (default)	Clonit Cloud (--cloud)
Credentials on this machine	Your own S3/R2 keys (in a storage profile)	None — uses your cloud session or API key
Where snapshots live	A bucket you own	Your org’s managed storage
How you address a pull	Snapshot index (clonit pull mydb 0)	Cloud snapshot ID (--snapshot-id)
Best for	Solo use, your own infrastructure, CI with its own bucket	Teams, new machines, sharing without distributing S3 keys
Cloud connection required	No	Yes

End-to-end example: share a sanitized snapshot with a teammate

# --- On your machine ---

# 1. Build, then sanitize a snapshot
clonit build mydb
clonit sanitize mydb

# 2. Push the sanitized snapshot to your org's managed storage
clonit push mydb --cloud

# --- On a teammate's machine (no S3 credentials needed) ---

# 3. Sign in to Clonit Cloud
clonit login

# 4. Find the shared snapshot's cloud ID
clonit cloud snapshots

# 5. Pull it by ID
clonit pull mydb --cloud --snapshot-id <id>

# 6. Load it into the local dev database
clonit load mydb

Note

Both pathways verify a SHA-256 checksum after every transfer to guard against corruption. Pass --no-verify to skip the check if you have a reason to.

See Also

• push – Full push command reference
• pull – Full pull command reference
• Connect Your Agent – Sign in and link this machine to Clonit Cloud
• Cloud Storage – Create and link a local storage profile
• snapshots – List snapshots and their indices for a target
• cloud – Manage the cloud connection and list cloud snapshots