Core Concepts
Access & Devices
Manage human device identities, environment-scoped roles, signed access requests, and the repository changes required to grant or revoke access.
Device identities
A device is a project-scoped cryptographic identity, not a user account. Joining creates a signing key, encryption key, self-signed public record, and local private identity. Private material is never committed.
$ ghostable access join --name "Sam Workstation"
$ ghostable access status
device is an alias for human-device operations; the broader access command also manages requests and automation credentials.
Inspect access
$ ghostable access list
$ ghostable access approvers --env production
$ ghostable access grants --env production
$ ghostable access matrix
The matrix is the quickest way to review effective roles by device and environment. Add --full only when complete device IDs are needed for an operation.
Requests and direct grants
A joining device can create a signed request that another authorized device reviews:
$ ghostable access requests create --env staging --role writer --reason "Joining release rotation"
$ ghostable access requests list
$ ghostable access requests approve --request-id <request-id> --reason "Approved by release owner"
For a direct grant, use access share with the target device ID, environment or all, and role.
Permission model
-
reader - Read and decrypt environment values.
-
writer - Reader permissions plus environment value changes.
-
grantor - Reader permissions plus access-grant authority for the environment.
-
owner - Read, write, grant, and owner authority across the project.
Grantor and writer are separate roles. A person who approves access does not automatically have permission to change values.
Revoke, leave, and delete
$ ghostable access revoke --device-id <device-id> --env all
$ ghostable access leave
$ ghostable access delete --device-id <revoked-device-id>
Revoke permanently marks the target identity as revoked, removes the selected grants, and automatically rotates keys for the affected environments. The --env option selects which grants and keys change; it does not make the identity reusable elsewhere. Use --env all for offboarding or compromise. A revoked device must join again with a new identity before it can receive access.
Leave removes the current machine's local project access. Delete removes an already-revoked public device record. Neither environment-key rotation nor record deletion erases secrets already seen by that device or rotates the credentials those values represent. The last owner cannot leave or be revoked, preserving a path to project administration.
Local cleanup
Find identities whose registered projects no longer exist, then remove them after review:
$ ghostable access cleanup --dry-run
$ ghostable access cleanup
