Publishing a repository

The operator flow — create a repository handle, dry-run the snapshot, publish it signed, and verify what readers will see.

This is the hands-on companion to the repositories concept: the four steps from "records on my instance" to "a signed publication anyone can read."

1. Create the handle

spl repo create acme/product-notes

The slash name is both the identity and the URL path. The namespace half (acme) is derived from the name; pass --namespace to override when the repository should live under a different one you own. Duplicate names are rejected.

Check what exists:

spl repo list
spl repo show acme/product-notes

2. Dry-run the snapshot

spl repo publish acme/product-notes --dry-run

The dry run builds and stages the full publish tree locally — nothing uploads, nothing becomes visible. Use it to see exactly what a publish would contain before the first real one, and as a pre-flight in scripts.

3. Publish

spl repo publish acme/product-notes

Publishing runs server-side on your instance and is owner-gated — only the identity that owns the namespace can publish under it. The command snapshots the repository's records, signs the snapshot and its listing with your identity, and uploads to published storage.

Useful flags:

Flag	What it does
`--visibility public`	Full detail (the default). Reduced-detail levels publish structure over content — see the Graph.
`--topic <topic>`	Advertise a topic on the listing (repeatable) so readers can find the repository by subject.
`--dry-run`	Stage locally, upload nothing.
`--json`	Machine-readable output for scripts.

Re-running publish advances the published state — each run is a fresh signed snapshot; readers always see the latest complete one.

Keep it published automatically

You don't have to re-publish by hand. Publishing with --relocation snapshots the whole instance as its portable form ("backup = publish"), and once a home is bound to a published repository the daemon's continuous write-back flushes new records to the published tree as they land — the publication follows your instance instead of trailing it. See Backup & restore for the recovery half of the same story.

4. Verify as a reader would

spl repo show acme/product-notes

Then open the public page:

https://graph.syncropel.com/acme/product-notes

Check the overview renders, the records tab shows what you intended to share, and nothing you meant to keep private is present — the published snapshot is exactly what a stranger sees, so review it as one.

Reading it back: clone, mount, fork

A published repository is not just a page — it is a complete, verified copy other machines can attach to:

# A fresh home from a publication — the `git clone` equivalent.
spl repo clone syncropel://acme/product-notes

# Pull ONLY what changed since the last hydration (incremental).
spl repo mount syncropel://acme/product-notes

# A new branch as one pointer write — segments are shared, nothing is copied.
spl repo fork acme/product-notes experiments

The locator is a connection string (syncropel://{ns}/{repo}), an HTTPS base URL, or a local directory. clone and mount run client-side against a home whose daemon is not running — they verify every segment hash and record content-address before ingesting, then the daemon re-folds at next boot. mount on an already-bound home pulls only the segments past its watermark, so a routine sync is cheap.

To check how far a live instance has drifted from its publication without changing anything:

spl repo drift acme/product-notes

Exit 0 means aligned, 3 means drift (the output shows which side has what the other lacks).

Deploy keys — scoped access without your identity

For CI jobs, viewers, or another instance that should read (or write) one repository without holding your identity:

spl repo key acme/product-notes --scope read

The command is owner-gated and prints the bearer once — store it in your secret manager. The key carries a grant scoped to exactly repo:acme/product-notes:read (or read-write, which also allows publish and fork); it opens nothing else on the instance. Add --expires-days for a bounded lifetime, and revoke at any time with spl token revoke.

Unlisting — retract discovery, keep the data

spl repo unlist acme/product-notes

Unlisting retracts the repository's directory listing — it stops being discoverable — while the published tree itself stays in storage for anyone who already holds the locator or a deploy key. It removes discovery, not data. Owner-gated; re-publishing with a listing makes it discoverable again.

Troubleshooting

Symptom	Likely cause	Fix
`duplicate name` on create	The handle already exists on this instance.	`spl repo list` to see it; pick another name or publish the existing one.
Publish rejected as not owner	Your current identity doesn't own the namespace in the handle.	`spl identity show` to confirm who you are; create the handle under a namespace you own.
Published page missing recent records	Readers see the last snapshot, not your live instance.	Run `spl repo publish` again to advance the published state.