Getting Started
Team Onboarding
Add a developer through a signed, repository-reviewed device request without sharing another person's private key or copying a long-lived plaintext env file.
Join from the new device
After cloning the repository, the new team member creates a device identity:
$ ghostable access join --name "Alex MacBook"
This writes a self-signed public device record under .ghostable/devices/. The signing and encryption private keys stay in the platform secret store on that device.
Request access
The new device requests the least-privileged role it needs:
$ ghostable access requests create --env default --role writer --reason "Joining application team"
$ git add .ghostable && git commit -m "Request Ghostable access for Alex"
Open a pull request containing the device and request records. An owner or grantor can inspect the device label, public-key fingerprints, requested scope, and reason before approving it.
Approve the request
From a checkout containing the request, an authorized device lists and approves it:
$ ghostable access requests list
$ ghostable access requests approve --request-id <request-id> --reason "Approved for application development"
$ git add .ghostable && git commit -m "Grant Alex Ghostable access"
Approval creates or updates signed policy and per-device environment grants. For a direct grant, an owner or grantor may use ghostable access share --device-id <device-id> --env default --role writer instead.
The simplest review uses one pull request: the requester opens it, an authorized approver checks out or fetches that branch, adds the signed approval commit, and pushes it back to the same pull request. If branch permissions prevent that push, place the approval commit in a follow-up pull request and merge both before the requester attempts to decrypt values. Do not treat a request-only commit as completed access.
Verify access
Once the approval commit is merged, the new team member pulls it and verifies access:
$ git pull
$ ghostable access status
$ ghostable env pull --env default --file .env
A production-like pull also requires the local operating system's user-presence confirmation.
Roles
-
reader - Decrypt and read values in the environment.
-
writer - Includes reader access and may create, change, promote, or delete values.
-
grantor - Includes reader access and may grant or review access for the environment; it does not imply write access.
-
owner - Project-wide ownership with read, write, grant, and ownership authority.
Offboarding
For offboarding or a lost device, revoke the identity from every environment and commit all signed changes:
$ ghostable access revoke --device-id <device-id> --env all
$ git add .ghostable && git commit -m "Revoke retired Ghostable device"
Revocation permanently marks that device identity as revoked and automatically rotates each affected environment key. The device cannot be granted access again; it must rejoin with a new identity. Although --env can name one environment, it controls which grants and environment keys are changed—not whether the identity is globally revoked—so use all for offboarding and compromise response.
Rotation blocks the revoked identity from decrypting future Ghostable values. It cannot erase plaintext the device already read or secrets recoverable from older Git history. If compromise is possible, also rotate the underlying database password, API key, or provider credential at its issuer. A revoked public device record can be deleted later with ghostable access delete. Ghostable prevents revoking or removing the last owner.