Sharing Snapshots

Once a snapshot lives in Clonit Cloud (see Push & Pull via Cloud), you can share it so other people in your organization can find and pull it. Sharing is how a sanitized snapshot moves from “mine” to “the team’s” without anyone touching production again.

This page covers what sharing controls, how to share and unshare a snapshot, how the Shared filter works, and exactly which snapshots a given user is allowed to see and pull.

Note

Sharing applies only to snapshots that have been uploaded to Clonit Cloud. Local snapshots and snapshots in your own S3/R2 bucket are not affected by these controls. Make sure you have connected your agent and are signed in first.

What sharing does

Every cloud snapshot starts out private: only you (the person who pushed it) and your organization’s owners and admins can see it. Sharing widens that audience:

• Share within the org — a single toggle that makes the snapshot visible and pullable to everyone in your organization, regardless of role.
• Share with a team (group) — grant access to a specific SSO group instead of the whole org.

Choose the org-wide toggle when the whole organization should be able to pull the snapshot; choose a group share when only one team needs it.

Sharing never changes the snapshot’s contents or its checksum. It only changes who is allowed to list and pull it.

Tip

Sanitize before you share. Sharing makes a snapshot reachable by more people, so run it through sanitization (and optionally cloud AI analysis) before you flip the share toggle.

Listing cloud snapshots

To see the snapshots your organization has in the cloud, run:

clonit cloud snapshots

The output includes a Shared column so you can tell at a glance which snapshots are shared org-wide:

ID        Target    Name                    Type       Size    Shared  Created
a1b2c3d4  mydb      mydb-20260622T120000    sanitized  120 MB  Yes     2026-06-22 12:00:00
e5f6g7h8  mydb      mydb-20260621T090000    snapshot   245 MB  No      2026-06-21 09:00:00

The ID column is the cloud snapshot ID (shown truncated). You’ll use it when pulling a specific snapshot from the cloud.

clonit cloud snapshots needs a configured cloud connection — see Connect Your Agent.

Sharing and unsharing a snapshot

Share and unshare are managed from the Snapshots page in the web UI. Start the web UI and open it in your browser:

clonit serve

Then open http://127.0.0.1:8484 and go to the Snapshots page. It lists local and cloud snapshots side by side — rows that exist in the cloud carry a cloud or synced badge and a Sharing control.

In the Sharing column, each snapshot with a cloud copy shows its state:

• A snapshot that is not shared shows Private. Click it to make the snapshot visible to your whole organization — the control flips to Shared.
• A snapshot that is already shared shows Shared. Click it to unshare — the snapshot becomes private again and the control flips back to Private.

Unsharing takes effect immediately: people who could only see the snapshot because it was shared will no longer find it in their listings.

Caution

Unsharing does not delete the snapshot or revoke any copies people have already pulled. It only stops new access through the cloud. If a snapshot was shared by mistake, unshare it and rotate the data if the contents were sensitive.

The Shared filter

The Snapshots page has a filter row:

• All — every snapshot: local ones on this agent plus every cloud snapshot you’re allowed to see (see Who can see and pull a snapshot below).
• Local — snapshots that exist on this agent (including synced ones).
• Cloud — snapshots that exist in the cloud (including synced ones).
• Shared — only the snapshots whose cloud copy is shared.

Switch to the Shared filter to focus on the snapshots that have been published for the team — this is usually where you’ll go to find a ready-to-pull, sanitized dataset that someone else built. Cloud snapshots have a Pull action right on the row; if the snapshot’s target isn’t on your agent yet, Clonit creates it for you before downloading.

Sharing with a team (group)

If you only want one team to access a snapshot — rather than the entire organization — share it with a group instead of toggling the org-wide share.

Groups in Clonit Cloud come from your identity provider (for example Okta) via SSO. Clonit reads your group memberships automatically when you sign in; it never manages user accounts or group membership itself. See Organizations & Teams for how groups fit into your org and Sign In & Login for how identity works.

Group shares are now manageable three ways: through the web UI Sharing dialog on the Snapshots page, the CLI, or the REST API.

Web UI

On the Snapshots page, open the Sharing dialog (click the Sharing control on any cloud snapshot). The dialog shows:

• An org-wide toggle to share the snapshot with your entire organization
• A Groups list showing SSO groups your organization has; select or deselect any group to grant or revoke access

Changes take effect immediately.

CLI

Use the following CLI commands to share and unshare snapshots:

# Share a snapshot with a group (by name or ID)
clonit cloud snapshots share <snapshot-id> --group <group-name-or-id>

# Unshare a snapshot from a group
clonit cloud snapshots unshare <snapshot-id> --group <group-name-or-id>

# Toggle org-wide share (without --group)
clonit cloud snapshots share <snapshot-id>
clonit cloud snapshots unshare <snapshot-id>

# List all group shares for a snapshot
clonit cloud snapshots shares <snapshot-id>

Important: Group-share changes made through the CLI or agent-mount API endpoints require a user-scoped API key (prefixed cak_). Org-level keys (clt_ or sak_) cannot attribute the user making the change and are rejected with an error. See API Keys for how to generate a user-scoped key.

REST API

Group shares are also available via the Clonit Cloud REST API. The agent-mount endpoints mirror the CLI:

Action	Endpoint
Share a snapshot with a group	POST /api/v1/agents/snapshots/{id}/share-group (body: {"group_id": "..."})
Remove a group share	DELETE /api/v1/agents/snapshots/{id}/share-group/{groupId}
List a snapshot’s group shares	GET /api/v1/agents/snapshots/{id}/group-shares
List your organization’s SSO groups (to find group IDs)	GET /api/v1/agents/org/sso/groups

Who can see and pull a snapshot

The same access rules decide which snapshots appear in your listings (in the CLI and the web UI) and which ones you can pull.

First, a rule that applies regardless of sharing: your own snapshots — the ones you pushed — are always visible to you. Sharing controls what others see, not what you see. Beyond that, access depends on your role in the organization:

• Owners and admins can see, pull, and delete every snapshot in the organization, shared or not.
• Members and viewers can see and pull a snapshot only if at least one of the following is true:
  • they own it (they pushed it), or
  • the snapshot is shared with the whole org, or
  • the snapshot is shared with an SSO group they belong to, or
  • the snapshot was shared to their organization by another organization (see the note below).

Snapshots you’re not allowed to access are simply hidden — they don’t show up in any listing, and trying to reach one directly behaves as if it doesn’t exist. This is deliberate: it avoids revealing that a snapshot exists at all.

Sharing with another organization

Organization admins can share snapshots with other organizations in your Clonit Cloud instance. Cross-org shares grant read-only access: the recipient organization can see and pull the snapshot but cannot modify or delete it. Shares can carry an expiry date and are revoked by the recipient org’s slug.

Cross-org shares are managed from the web UI Sharing dialog, the CLI, or the REST API. All three require the admin role, and CLI/agent-mount changes additionally need a user-scoped API key (cak_): org-level keys (clt_ or sak_) cannot attribute the acting user and are rejected with user_attribution_required. See API Keys for how to generate a user-scoped key.

Web UI

On the Snapshots page, open the Sharing dialog on any cloud snapshot. Below the org-wide toggle and the SSO groups list, the Other organizations section lists the snapshot’s current cross-org shares (with an expiry badge where one is set) and lets you share to a new organization by entering its slug, or revoke an existing share. If you are not an org admin, the section shows a short note instead — the rest of the dialog keeps working.

CLI

# Share a snapshot with another organization (by slug), no expiry
clonit cloud snapshots share <snapshot-id> --org <org-slug>

# Share with an expiry, relative to now (e.g. 30 days)
clonit cloud snapshots share <snapshot-id> --org <org-slug> --expires-in 720h

# Revoke a cross-org share
clonit cloud snapshots unshare <snapshot-id> --org <org-slug>

# List a snapshot's shares — cross-org shares appear after group shares
clonit cloud snapshots shares <snapshot-id>

Sharing again with the same organization updates the existing share (for example, to change the expiry). shares prints the cross-org section only for admins; other callers see a note that the listing requires an org admin.

REST API

The agent-mount endpoints mirror the CLI (admin + user-scoped key):

Action	Endpoint
Create or update a cross-org share	POST /api/v1/agents/snapshots/{id}/share-org (body: {"org_slug": "...", "expires_at": optional RFC3339})
Revoke a cross-org share	DELETE /api/v1/agents/snapshots/{id}/share-org/{slug}
List a snapshot’s cross-org shares	GET /api/v1/agents/snapshots/{id}/org-shares

The same routes exist on the JWT API at /api/v1/snapshots/{id}/… for browser-session callers.

The recipient organization is identified by its slug. Shares automatically expire when expires_at is reached; omit it for a share that never expires.

When another organization has shared a snapshot to yours, it appears in your Shared listing and can be pulled. Access is read-only — you can never delete it from your side.

Note

Cross-org shares are visible to:

• The sharing organization: the owner/admin who created the share
• The recipient organization: members and viewers see them in the Shared listing (admins see all snapshots anyway)

Note

Roles in short: owner and admin have full access; member and viewer see their own snapshots plus what’s been shared with them. Sharing a snapshot is the action that brings it into other members’ and viewers’ view.

Pulling a shared snapshot

Once a snapshot is shared with you, find its ID and pull it from the cloud:

# 1. Find the snapshot you're allowed to pull
clonit cloud snapshots

# 2. Pull it from the cloud by ID
clonit pull mydb --cloud --snapshot-id a1b2c3d4...

The --cloud flag tells clonit to download through Clonit Cloud (using a presigned URL) instead of a local storage profile, and --snapshot-id selects the exact cloud snapshot. After it downloads, load it into your dev database as usual:

clonit load mydb

For the full push/pull flow and verification options, see Push & Pull via Cloud.

Typical workflow

A common end-to-end flow for publishing a sanitized snapshot to your team:

# 1. Build and sanitize a snapshot locally
clonit build mydb
clonit sanitize mydb

# 2. Push the sanitized snapshot to the cloud
clonit push mydb --cloud

# 3. Share it (Snapshots page → Sharing → Private/Shared toggle), then teammates pull it
clonit cloud snapshots          # teammate finds the shared snapshot + its ID
clonit pull mydb --cloud --snapshot-id <id>
clonit load mydb

See also

• Push & Pull via Cloud — upload and download cloud snapshots
• Connect Your Agent — register your agent with the cloud
• Sign In & Login — clonit login and how identity works
• Organizations & Teams — roles, members, and groups
• cloud command reference — all clonit cloud subcommands
• pull command reference — flags for pulling snapshots