cloud

Manage the Clonit Cloud connection.

Usage

clonit cloud [command]

Subcommands

Subcommand	Description
register	Register this agent with Clonit Cloud
status	Show cloud connection status
sync	Sync local target definitions to Clonit Cloud
pull-targets	Localize Clonit Cloud targets into full local rows
targets	List cloud targets
targets add	Add a target to the cloud
snapshots	List cloud snapshots
snapshots share	Share a cloud snapshot org-wide, with an SSO group, or with another org
snapshots unshare	Stop sharing a cloud snapshot org-wide, with an SSO group, or with another org
snapshots shares	List a cloud snapshot’s SSO group and cross-org shares
storage-profiles	List cloud storage profiles (alias: sp)
storage-profiles add	Add a storage profile to the cloud
storage-profiles update	Update a cloud storage profile
storage-profiles verify	Verify a storage profile and print the AWS onboarding artifact
api-keys	List cloud API keys with their scope and permissions (alias: keys)
api-keys create	Create a cloud API key, optionally target-scoped and permission-limited
api-keys delete	Delete a cloud API key by name or id
analysis-key set	Set (or replace) the org’s Anthropic key for cloud-side analysis
analysis-key status	Show whether an org analysis key is set, plus metered usage
analysis-key clear	Clear the org’s Anthropic key for cloud-side analysis

Description

Clonit Cloud adds team collaboration, cross-device access, and snapshot sharing. These commands require cloud.url and cloud.api_key to be configured.

To configure the cloud connection, set cloud.url and cloud.api_key with clonit config edit, then run clonit cloud register to register this agent.

---

cloud register

Register this agent with Clonit Cloud.

Usage

clonit cloud register [flags]

Flags

Flag	Type	Default	Description
--force	bool	false	Re-register even if already registered
--name	string	hostname	Agent name

Examples

Register this agent with the cloud (defaults the agent name to the hostname):

clonit cloud register

Register with a custom agent name:

clonit cloud register --name ci-runner-01

Re-register an already-registered agent:

clonit cloud register --force

---

cloud status

Show cloud connection status.

Usage

clonit cloud status

Examples

clonit cloud status

---

cloud sync

Sync local target definitions to Clonit Cloud.

Uploads local target definitions to Clonit Cloud so they can be resolved from other devices or agents. The non-secret configuration (database type, subset and schema rules, parallel-job counts, the read-only flag, and the active sanitize query text) is always sent. How the database password is handled is controlled by --secret-mode:

• runtime (default) — send password-less URL skeletons; each agent supplies the password from its own environment (PGPASSWORD / MYSQL_PWD) at run time. No DB password leaves this host.
• templated — replace the password with an environment placeholder ({{ env "PGPASSWORD" }} / {{ env "MYSQL_PWD" }}) that the retrieving agent expands. No DB password leaves this host.
• encrypted — upload the full URL including the password over TLS; the cloud encrypts it at rest and returns it only via an audited, access-gated per-target retrieve.

See Database Credentials for how the modes compare and when to use which. Storage credentials are never uploaded in any mode (they are brokered server-side).

Usage

clonit cloud sync [flags]

Flags

Flag	Type	Default	Description
--target	string	all	Sync a specific target
--secret-mode	string	runtime	DB password handling: runtime, templated, or encrypted

Examples

Sync all local targets to the cloud:

clonit cloud sync

Sync a single target:

clonit cloud sync --target mydb

Sync with the password templated as an environment placeholder:

clonit cloud sync --secret-mode templated

---

cloud pull-targets

Localize Clonit Cloud targets into full local rows.

You usually do not need this: cloud targets are usable without pulling — the agent localizes a cloud target on first use. Use pull-targets to pre-create the local rows explicitly (for example on a fresh CI/CD or ephemeral machine).

Pull localizes everything the cloud can provide: connection URLs (materialized per the target’s secret mode), the non-secret configuration (subset/schema rules, jobs, read-only, keyless database auth posture, per-target AWS profile), storage-profile bindings (same-named local profiles are created from the cloud’s non-secret metadata with empty credentials — secrets never leave the cloud; fill in access keys or an AWS profile locally before direct pushes), and the active sanitize query. Pulling an encrypted-mode target fires the audited config retrieve for that target. Only targets that don’t already exist locally are localized.

Usage

clonit cloud pull-targets [flags]

Flags

Flag	Type	Default	Description
--name	string	all	Import a specific target

Examples

Import all cloud targets that don’t exist locally:

clonit cloud pull-targets

Localize a single target:

clonit cloud pull-targets --name mydb

---

cloud targets

List cloud targets.

Usage

clonit cloud targets

Examples

clonit cloud targets

---

cloud targets add

Add a target to the cloud.

Usage

clonit cloud targets add <name> [flags]

Arguments

Argument	Description	Required
name	Name of the cloud target to add	Yes

Flags

Flag	Type	Default	Description
--db-type	string	postgres	Database type (postgres, mysql)
--description	string		Target description

Examples

Add a cloud target:

clonit cloud targets add mydb

Add a MySQL cloud target with a description:

clonit cloud targets add analytics --db-type mysql --description "Reporting warehouse"

---

cloud snapshots

List cloud snapshots.

Usage

clonit cloud snapshots

Examples

clonit cloud snapshots

---

cloud snapshots share

Share a cloud snapshot with your org, with an SSO group, or with another organization.

Without flags, the snapshot’s org-wide shared flag is set — every member of your organization can see it. With --group, the snapshot is shared with a single SSO group instead; the value matches a group name first, then a group ID, and an unknown value fails with the list of available groups. With --org, the snapshot is shared with another organization, identified by its slug; add --expires-in for an expiring share. --group and --org are mutually exclusive. Cross-org shares require the admin role and a user-scoped API key (cak_) — org-level keys are rejected with user_attribution_required. See Sharing Snapshots for how the share kinds combine.

Usage

clonit cloud snapshots share <snapshot-id> [flags]

Arguments

Argument	Description	Required
snapshot-id	ID of the cloud snapshot to share	Yes

Flags

Flag	Type	Default	Description
--group	string		SSO group name or ID to share with (omit for an org-wide share)
--org	string		slug of another organization to share with (admin, user-scoped key)
--expires-in	duration		expiry for a cross-org share, from now (e.g. 720h; only with --org, omit for no expiry)

Examples

Share a snapshot with the whole org:

clonit cloud snapshots share 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa shared with the org.

Share a snapshot with the data-eng SSO group:

clonit cloud snapshots share 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa --group data-eng
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa shared with group "data-eng".

Share a snapshot with the acme organization for 30 days:

clonit cloud snapshots share 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa --org acme --expires-in 720h
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa shared with org Acme Corp (acme), expires 2026-08-19T12:00:00Z.

---

cloud snapshots unshare

Stop sharing a cloud snapshot.

Without flags, the org-wide shared flag is removed (existing group and cross-org shares are untouched). With --group, only the share to that SSO group is revoked; the value matches a group name first, then a group ID. With --org, the cross-org share to that organization (identified by slug) is revoked — admin role and a user-scoped key required. --group and --org are mutually exclusive.

Usage

clonit cloud snapshots unshare <snapshot-id> [flags]

Arguments

Argument	Description	Required
snapshot-id	ID of the cloud snapshot to unshare	Yes

Flags

Flag	Type	Default	Description
--group	string		SSO group name or ID to unshare from (omit to clear the org-wide share)
--org	string		slug of the organization whose cross-org share to revoke

Examples

Clear a snapshot’s org-wide share:

clonit cloud snapshots unshare 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa is no longer shared with the org.

Revoke only the data-eng group share:

clonit cloud snapshots unshare 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa --group data-eng
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa is no longer shared with group "data-eng".

Revoke the cross-org share to the acme organization:

clonit cloud snapshots unshare 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa --org acme
Snapshot 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa is no longer shared with org "acme".

---

cloud snapshots shares

List the SSO group and cross-org shares of a cloud snapshot. Group IDs are resolved to group names where possible, and the snapshot’s org-wide shared state is printed above the tables (best-effort — skipped if the snapshot list can’t be fetched). Cross-org shares are listed after group shares; the cloud gates that list to org admins, so non-admin callers see a note that the cross-org section is hidden instead of an error.

Usage

clonit cloud snapshots shares <snapshot-id>

Arguments

Argument	Description	Required
snapshot-id	ID of the cloud snapshot to inspect	Yes

Examples

clonit cloud snapshots shares 8f4e2a1b-6c0d-4f3a-9b1e-2d7c5a90f3aa
Org-wide share: no
Group      Shared By                              Created
data-eng   b7c9d2e1-4f5a-4b6c-8d9e-0a1b2c3d4e5f   2026-07-15T18:22:04Z
Org    Name       Expires                Created
acme   Acme Corp  2026-08-19T12:00:00Z   2026-07-20T09:15:00Z

---

cloud storage-profiles

List your organization’s cloud storage profiles. The group has the alias sp, and running the bare group is the same as list. The table shows Name, Provider, Auth Mode, Bucket, Region, and Role ARN.

Cloud storage profiles support two auth modes: static (the default — access/secret keys, encrypted at rest in the cloud) and assume_role (S3-only keyless mode — the cloud stores a role ARN plus a server-minted ExternalId and no keys). See Keyless Credentials for how the keyless mode works.

Usage

clonit cloud storage-profiles [list]
clonit cloud sp [list]

Examples

clonit cloud storage-profiles
clonit cloud sp list

---

cloud storage-profiles add

Add a storage profile to the cloud.

With --auth-mode assume_role, the profile must use --provider s3 and a --role-arn; a custom --endpoint, --access-key, or --secret-key is rejected (the mode is keyless), and an unknown --auth-mode value fails before anything is sent to the cloud. After creating an assume_role profile, the command prints a reminder to run clonit cloud storage-profiles verify <name> to get the AWS trust-policy onboarding artifact.

Usage

clonit cloud storage-profiles add [flags]

Flags

Flag	Type	Default	Description
--name	string		Profile name (required)
--provider	string	s3	Storage provider (s3, r2)
--bucket	string		Bucket name (required)
--region	string		Bucket region
--prefix	string		Object key prefix
--account-id	string		Provider account id (r2)
--endpoint	string		Custom S3-compatible endpoint (not allowed with assume_role)
--access-key	string		Access key (static auth mode only)
--secret-key	string		Secret key (static auth mode only)
--auth-mode	string	static	Auth mode: static or assume_role (S3-only keyless AssumeRole)
--role-arn	string		Customer IAM role ARN to assume (--auth-mode assume_role)

Examples

Add a static-key profile (the default auth mode):

clonit cloud storage-profiles add \
  --name team-snapshots \
  --bucket my-snapshots \
  --region us-east-1 \
  --access-key AKIA... \
  --secret-key wJalr...

Add a keyless (AssumeRole) profile, then fetch the onboarding artifact:

clonit cloud storage-profiles add \
  --name team-keyless \
  --bucket my-snapshots \
  --region us-east-1 \
  --auth-mode assume_role \
  --role-arn arn:aws:iam::123456789012:role/clonit-access

clonit cloud storage-profiles verify team-keyless

---

cloud storage-profiles update

Update a cloud storage profile. Only fields whose flags are set change; everything else keeps its current value (the cloud applies the update as a full replace, so the current profile is loaded first).

Switching auth modes migrates the profile in place — the profile id stays stable, so snapshots that reference it are never orphaned:

• --auth-mode assume_role --role-arn <arn> clears any stored keys and mints a new ExternalId server-side. Run clonit cloud storage-profiles verify <name> to get the updated onboarding artifact — any previously attached trust policy references the old ExternalId and must be replaced.
• --auth-mode static --access-key ... --secret-key ... clears the role ARN and the ExternalId; keys must be re-supplied (the cloud never returns stored keys, so there is nothing to fall back to).

Usage

clonit cloud storage-profiles update <name> [flags]

Arguments

Argument	Description	Required
name	Name of the cloud storage profile to update	Yes

Flags

Flag	Type	Default	Description
--name	string	unchanged	New profile name
--provider	string	unchanged	Storage provider (s3, r2)
--bucket	string	unchanged	Bucket name
--region	string	unchanged	Bucket region
--prefix	string	unchanged	Object key prefix
--account-id	string	unchanged	Provider account id
--endpoint	string	unchanged	Custom S3-compatible endpoint (pass '' to clear)
--access-key	string		Access key (static auth mode only)
--secret-key	string		Secret key (static auth mode only)
--auth-mode	string	unchanged	Auth mode: static or assume_role
--role-arn	string		Customer IAM role ARN to assume (--auth-mode assume_role)

Examples

Migrate a static profile to keyless AssumeRole (keys are cleared, a new ExternalId is minted):

clonit cloud storage-profiles update team-snapshots \
  --auth-mode assume_role \
  --role-arn arn:aws:iam::123456789012:role/clonit-access

clonit cloud storage-profiles verify team-snapshots

Migrate back to static keys (the role ARN and ExternalId are cleared; keys must be re-supplied):

clonit cloud storage-profiles update team-snapshots \
  --auth-mode static \
  --access-key AKIA... \
  --secret-key wJalr...

Change a single field, leaving everything else as-is:

clonit cloud storage-profiles update team-snapshots --bucket new-snapshots

---

cloud storage-profiles verify

Verify a cloud storage profile and print the AWS onboarding artifact.

For an assume_role profile, the cloud performs a throwaway sts:AssumeRole into your IAM role and reports whether the trust policy + ExternalId are wired correctly, then prints the copy-pasteable onboarding artifact: the cloud’s principal ARN, the ExternalId, and the trust and permission policy JSON. The ExternalId is surfaced only by this command — it is never returned by any other API response, so copy it when you see it.

The first verify after creating (or migrating to) an assume_role profile is expected to fail — your IAM role doesn’t trust the cloud principal yet. Attach the printed trust and permission policies to the role, then re-run verify. The command exits non-zero when verification fails, so it is safe to use as a gate in scripts.

Usage

clonit cloud storage-profiles verify <name>

Arguments

Argument	Description	Required
name	Name of the cloud storage profile to verify	Yes

Examples

clonit cloud storage-profiles verify team-keyless

---

cloud api-keys

List the organization’s Clonit Cloud API keys. The group has the alias keys, and running the bare group is the same as list. The table shows Name, Key Prefix, Permissions, Scope, and Created. Scoped target ids are resolved to target names where possible; a key with no scope shows full org, and an empty permission list shows all.

API keys authenticate machines (CI/CD pipelines, headless agents). See API Keys for when to use one instead of clonit login.

Usage

clonit cloud api-keys [list]

---

cloud api-keys create

Create a Clonit Cloud API key for the organization (admin role required). The full clt_… key is printed once — copy it immediately; only the prefix is shown afterwards.

A key can be confined to a least-privilege subset of the org:

• --scope-target <name> (repeatable) confines the key to a strict allowlist of cloud targets: target listing, config retrieve, and snapshot pull only reach targets in the scope. Snapshot push is allowed only when the key is unscoped or the target is in the scope — a group-only scope grants no push. Names resolve against the org’s cloud target catalog with an exact, case-sensitive match; an unknown name fails the command and lists the available cloud targets.
• --permissions pull,push gates the snapshot data-plane operations the key may perform. Omitting the flag grants all permissions.

Usage

clonit cloud api-keys create --name <name> [flags]

Flags

Flag	Type	Default	Description
--name	string		Key name — name keys after where they run (required)
--scope-target	string (repeatable)		Confine the key to this cloud target, by exact name
--permissions	strings	all	Data-plane permissions: pull, push (empty = all)

Examples

A least-privilege key for a CI/CD agent that only downloads snapshots of one target:

clonit cloud api-keys create --name ci-pull --scope-target proddb --permissions pull

A push-and-pull key confined to two targets:

clonit cloud api-keys create --name nightly-runner \
  --scope-target proddb --scope-target staging

A full-org key (no scope, all permissions):

clonit cloud api-keys create --name org-fallback

---

cloud api-keys delete

Delete a Clonit Cloud API key by name or id (admin role required). Deletion is immediate: any agent authenticating with the key loses access on its next request. If two keys share a name, the command reports the ambiguity and asks for the id.

Usage

clonit cloud api-keys delete <name-or-id>

Examples

clonit cloud api-keys delete ci-pull

---

cloud analysis-key

Manage the organization’s Anthropic API key that Clonit Cloud uses to run sanitization analysis server-side. The key is encrypted at rest in the cloud and never displayed again after it is set.

These commands act as you, not as this agent: they use the login session from clonit login, and set/clear require the org admin or owner role. When set, the org key wins over the deployment’s shared key. See Cloud AI Analysis for the full key-precedence ladder.

Usage

clonit cloud analysis-key set [key] [flags]
clonit cloud analysis-key status
clonit cloud analysis-key clear

Flags

Flag	Type	Default	Description
--model	string	deployment default	Model override for this org (set only)

Examples

Set the key by prompt (input hidden, so it stays out of shell history):

clonit cloud analysis-key set

Pass the key inline, or pipe it from a secret manager:

clonit cloud analysis-key set sk-ant-...
op read "op://Vault/item/credential" | clonit cloud analysis-key set

Show whether a key is configured, plus metered analysis usage:

clonit cloud analysis-key status

Clear the org key (cloud analysis falls back to the deployment key, if any):

clonit cloud analysis-key clear

See Also

• login – Log in to Clonit Cloud via your browser
• logout – Log out of Clonit Cloud and clear the stored session
• push – Push a snapshot to remote storage (use --cloud for managed storage)
• pull – Pull a snapshot from remote storage (use --cloud for managed storage)
• targets – List local targets
• Keyless Credentials – The S3 AssumeRole (keyless) storage mode in depth
• Database Credentials – Every way Clonit handles a database password, including the sync secret modes
• Clonit Cloud overview – What Clonit Cloud adds