Skip to content
PatchArc

Sharing and ArcLinks

Sign in with the device flow, upload a sealed capsule, get a server-verified ArcLink, and revoke or rotate it.

validated against patcharc 0.2.0 · 2026-08-22

Sharing is the only part of PatchArc that talks to the network. It uploads a capsule you already sealed, the cloud re-verifies it, and you get a short link.

Sign in

$ patcharc login
To authenticate, visit: https://patcharc.dev/device?code=KQ7P-MX2A-91ZC
and enter code:         KQ7P-MX2A-91ZC
Waiting for approval…
✓ Logged in to PatchArc Cloud
  account:     acc_…
  user:        usr_…
  credentials: ~/.patcharc/credentials.json (0600)

This is an OAuth device flow: the CLI requests a code, opens the approval page in your browser (it prints the URL if it cannot), you sign in with GitHub or Google, approve the code, and the CLI polls until it receives a token. Codes expire after ten minutes; run login again if one does. The first sign-in creates a personal account. See Accounts and sessions for where credentials live and how to log out.

Share a capsule

$ patcharc share --visibility public
✓ Uploaded arc_8f2c1d4a9b.parc (48213 bytes, sha256 9f1c2e…)
  capsule: cap_… (verifying)
  ArcLink: https://patcharc.dev/a/X9kQ2mN4vR7s

What happens, in order:

  1. The CLI picks the newest .parc in .patcharc/capsules/ (or the one you pass with --file) and hashes it.
  2. It opens an upload session (POST /v1/upload-sessions) declaring the size and SHA-256, then streams the file. The server refuses a body whose hash does not match what was declared.
  3. It marks the upload complete. A per-capsule Durable Object re-verifies the Ed25519 signature and every file hash inside the capsule. A capsule that fails is marked failed_terminal and is never published.
  4. The CLI polls the status every 2 seconds for up to 2 minutes, then creates the share and prints the ArcLink.

Flags

FlagDefaultMeaning
--file <path>newest capsuleWhich .parc to upload
--visibilitypublicpublic, private, team, or capability
--openoffOpen the ArcLink in your browser after it prints
--no-aionSkip the AI summary. AI summaries are not generated in 0.2.0, so this flag has no effect yet
Default is public

share defaults to --visibility public: anyone with the URL can open the link. The slug has at least 96 bits of entropy and is not listed anywhere, but treat it as a secret URL, and read the capsule with patcharc inspect before you share it. The redaction engine is not applied automatically in 0.2.0.

Visibility

ValueWho can open the link today
publicAnyone with the URL
capabilityAnyone with the URL (same as public in 0.2.0; per-link rate limits are planned)
privateAccepted by the API, but the browser viewer for signed-in access is not available yet; the link answers 401
teamSame as private; organisations and teams are not built yet

Use public or capability for links you intend people to open.

In 0.2.0 the ArcLink page is a minimal server-rendered view: the Arc id, and the published review record for the capsule. The rich six-section viewer is planned; today the full review lives in the capsule itself (evidence/summary/review.json), which anyone can read after patcharc verify.

Expiry, revoke, rotate

Links expire 30 days after creation by default. Revocation and rotation are API calls in 0.2.0 (patcharc revoke prints the endpoint rather than calling it):

# revoke: the link answers 410 immediately
$ curl -X DELETE https://api.patcharc.dev/v1/shares/<share_id> \
    -H "Authorization: Bearer $(jq -r .refresh_token ~/.patcharc/credentials.json)"

# rotate: new slug, old slug stops resolving
$ curl -X POST https://api.patcharc.dev/v1/shares/<share_id>/rotate \
    -H "Authorization: Bearer $(jq -r .refresh_token ~/.patcharc/credentials.json)"

# extend or clear expiry
$ curl -X PATCH https://api.patcharc.dev/v1/shares/<share_id> \
    -H "Authorization: Bearer …" -H "content-type: application/json" \
    -d '{"expires_at": null}'

Every share, revoke, and rotate writes an audit event. See the Cloud API reference for the share id in the create response.

Deleting a capsule

DELETE /v1/capsules/<capsule_id> removes the stored capsule, its derived review, and every share for it in one cascade. Locally, delete the .parc file; the server keeps nothing you did not upload.