sem cloud · product flow

Cloud is off until the repo owner says yes.

sem can answer graph queries from pre-built cloud indexes, but the CLI keeps login, discovery, public enablement, private sharing, preview, and deletion as separate user-visible states.

Default

Local only

Public repo

Enable asks [y/N]

Private repo

Type repo name

Audit

Local ledger

Invariant: logging in does not register a repo, upload an index, or send a query. Cloud routing starts only after sem cloud enable for a public repo, sem cloud share for a private repo, or an explicit CI environment override.

The product flow

The consent boundary is a command surface, not a hidden prompt inside a query. Slow local runs may show a passive tip, but printing the tip sends nothing.

Consent states

The state machine is intentionally small. It is stored per normalized remote URL in ~/.sem/cloud.json.

enabled

Public repo

sem cloud enable confirms GitHub says the repo is public, then asks before registration.

shared

Private repo

sem cloud share requires typing the repo name and warns that sem can technically read the parsed index.

never

Stay local

sem cloud never records a no-cloud decision for this repo, or suppresses the discovery tip globally outside a repo.

What the user sees

The CLI copy makes the data boundary visible before any approving choice.

sem cloud enable

$ sem cloud enable
Cloud queries send: this repo's URL + the entity/file names you query, linked to your account.
This is not anonymous — it's tied to your sem account.

No query has left this machine yet.

Enable cloud queries for ataraxy-labs/sem? [y/N]

sem cloud share

$ sem cloud share
Sharing a PRIVATE repo uploads its parsed index to sem cloud:
  • encrypted at rest, isolated per tenant. NOT end-to-end: sem can technically read it.
  • undo anytime — delete everything with sem cloud forget.

Type the repo name to confirm (ataraxy-labs/private-repo):

Data boundary

The product promise is concrete: show what may leave the machine, what never leaves, and where the user can inspect the ledger.

Surface	When	Data
login	When the user authenticates	Credentials are saved. No repo is registered and no query is sent.
register	After enable/share consent	Normalized clone URL and visibility (`public` or `private`).
impact/context	Only after active consent and clean working tree	Repo id, target entity, target file path, and context budget where relevant.
preview	Any time inside a repo	Sends nothing; prints the exact request shape.
log	Any time	Reads local `~/.sem/cloud-log.jsonl`; sends nothing.

Private repositories are never silently uploaded. If GitHub does not confirm a repo is public, sem cloud enable stops and points to the louder sem cloud share flow.

User controls

sem cloud status

Shows account, endpoint, telemetry mode, this repo's state, and the list of active cloud-enabled repos.

sem cloud preview

Shows the exact cloud request without sending it. This is the transparency screen for security review.

sem cloud log

Prints the local outbound ledger: timestamp, normalized repo, request kind, and detail.

sem cloud forget

Asks for confirmation, deletes the cloud index if possible, clears local consent, evicts repo cache, and records the deletion locally.

Runtime routing

Cloud is a fast path, not the only path. If consent is absent, the repo is dirty, network is disabled, or the cloud repo is not ready, sem falls back to local graph computation.

Condition	Result
no consent	Local execution. No cloud request.
dirty working tree	Local execution so answers reflect uncommitted changes.
SEM_LOCAL=1	Cloud routing disabled.
SEM_NO_NETWORK=1	Cloud, telemetry upload, and update checks disabled.
SEM_CLOUD=1	CI/code-reviewed opt-in path that treats cloud as enabled.