append-upsert

Append a relationship.upsert event to the event feed.

Append a relationship.upsert event to the event feed. This creates or updates a relationship between an issuer and a subject.

Usage

ak append-upsert [FLAGS]

Flags

Flag	Required	Default	Description
`--events-path <PATH>`	Yes	—	Path to the `events.jsonl` file.
`--issuer <DID>`	Yes	—	Issuer DID (e.g., `did:web:example.com`).
`--event-id <ID>`	Yes	—	Unique event identifier.
`--relationship-id <ID>`	Yes	—	Stable relationship identifier.
`--subject <DID>`	Yes	—	Subject DID.
`--relationship-type <TYPE>`	Yes	—	One of: `employee`, `founder`, `contractor`, `advisor`, `investor`, `admin_delegate`, `other`.
`--roles <ROLES>`	Yes	—	Comma-separated list of roles.
`--issued-at <TIMESTAMP>`	Yes	—	RFC 3339 UTC timestamp (e.g., `2025-01-15T00:00:00Z`).
`--valid-from <TIMESTAMP>`	No	—	Validity start timestamp (RFC 3339 UTC).
`--valid-until <TIMESTAMP>`	No	—	Validity end timestamp (RFC 3339 UTC).
`--kid <KID>`	Yes	—	Key ID used for signing the event.
`--seed-hex <HEX>`	Yes	—	Hex seed for the signing key.

Relationship Types

Type	Description
`employee`	Full-time or part-time employee.
`founder`	Company founder.
`contractor`	Independent contractor or consultant.
`advisor`	Advisory role.
`investor`	Investor or board member.
`admin_delegate`	Delegated administrative authority.
`other`	Any relationship not covered above.

Example

ak append-upsert \
  --events-path ./issuer-root/.well-known/sig/events.jsonl \
  --issuer did:web:example.com \
  --event-id evt-001 \
  --relationship-id rel-alice-eng \
  --subject did:web:alice.example.com \
  --relationship-type employee \
  --roles "engineer,deploy" \
  --issued-at 2025-01-15T00:00:00Z \
  --valid-from 2025-01-15T00:00:00Z \
  --kid orgsign-1 \
  --seed-hex 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f

Output:

Appended relationship.upsert event evt-001 (seq=1)
  Relationship: rel-alice-eng
  Subject:      did:web:alice.example.com
  Type:         employee
  Roles:        engineer, deploy

Notes

The --relationship-id is a stable identifier. Issuing another upsert with the same relationship ID updates the existing relationship rather than creating a new one.
The --event-id must be unique across the entire feed.
Events are appended with an automatically incremented sequence number.
The --valid-from and --valid-until flags are optional. When omitted, the relationship has no explicit time bounds beyond the --issued-at timestamp.