Signing in and pairing

See the available routes

or login --list
or whoami

local.device creates an Ed25519 identity on this machine. app.keychain uses an Ourcana app identity on macOS, but only when this Orchard build has the required signing and provisioning. The listed magic.link and passkey routes are unavailable; Orchard cannot enroll through them.

or login chooses an available app identity by default, otherwise local.device. If the app has several identities, it asks you to choose instead of guessing.

Enroll a local identity

or login --route local.device
or whoami

Enrolling the same route again normally reuses its identity. --new forces another enrollment; for local.device, that creates a whole new system. Do not use it to recover access to an existing system.

Use an app identity on macOS

This requires the properly provisioned app bundle, not an unsigned Cargo binary.

or login --route app.keychain --namespace <namespace-hex-prefix>
or whoami

Replace angle-bracket placeholders before running commands. or estate --all can help identify which readable app identity has an Online entitlement. --namespace selects enrollment; whoami --use-id <prefix> switches between identities already enrolled in Orchard.

Pair a terminal

Pairing does not require the shared-keychain entitlement. First enroll a local identity, then print its subspace public key:

or login --route local.device
or pair

In the Ourcana app's Pair a terminal flow, paste that public key. Accept the file or code returned by the app:

or pair --accept ./pairing.json
# A pasted code must be quoted as one shell argument.
or pair --accept 'PASTED_CODE_FROM_THE_APP'

The CLI checks that the payload names its own subspace and that the app's delegation signature is valid. Version 2 includes the keys needed to decrypt mirrored paths and payloads. Version 1 is accepted for older pairings but must be replaced to obtain those keys.

Pairing stores a grant and token; it does not import the app's namespace identity into Orchard's keystore. In the current implementation, online uses an enrolled owned namespace and does not consume the stored pairing's E2E keys. Pairing alone therefore does not make online browse the app's namespace. connect checks the enrolled identity's handshake, not a full paired-data sync.

Delegate and forget

or login --link <subspace-hex> signs a Meadowcap delegation to another terminal's 32-byte subspace public key. Add --read-only for a read grant. This is not the full app pairing payload: it does not by itself supply a gate token or E2E keys.

or pair --forget removes the stored pairing and token. In JSON mode it succeeds without writing a JSON object. or logout <namespace-prefix> forgets matching enrolled identities; omit the prefix to forget all. These actions remove local records, not remote data or app identities. Back up local keys before forgetting an identity you may need again.

See the verbatim help for every flag.