Repository & Storage | Ghostable CLI 3.x | Ghostable Menu Repository & Storage Repository-backed state ----------------------- The `.ghostable/` directory is project state, not a local cache. It is intended to be committed, reviewed, branched, and merged with the application: ``` .ghostable/ ├── ghostable.yaml ├── policy.json ├── devices/ ├── access-requests/ ├── environments/ │ └── production/ │ ├── access/ │ ├── keys/ │ └── values/ ├── events/ ├── schema.yaml ├── schemas/ └── hygiene.yaml ``` Values are encrypted, while device, policy, key metadata, access, activity, and suppression records are signed so tampering can be detected. Deleting or hand-editing these files can invalidate the project state; use CLI commands whenever one exists. Local identity -------------- Each device has an Ed25519 signing key and X25519 encryption key. Public device records are committed. Private material is stored outside the repository: `macOS` Keychain service dev.ghostable.identity.<project-id>. `Windows` Credential Manager target dev.ghostable.identity.<project-id>. `Linux / Unix` ${XDG\_CONFIG\_HOME:-~/.config}/ghostable/identities/<project-id>.json. `GHOSTABLE_KEYSTORE` Optional identity-store override used for controlled environments and testing. File-backed identity directories use `0700` permissions and identity files use `0600` on Unix-like systems. Metadata visibility ------------------- Encryption protects secret values, not all context. Repository readers may see project and environment names, public device labels, access roles, variable key names, annotations, change reasons, event timing, and schema descriptions. Metadata must remain non-secret Never place credentials in a key name, annotation, schema description, change reason, commit message, or pull-request discussion. Use encrypted variable context when a confidential note is required. Git workflow ------------ Review Ghostable changes alongside the code that consumes them: Review repository state Copy ``` $ ghostable validate --env staging $ ghostable review $ git diff -- .ghostable $ git add .ghostable && git commit -m "Update staging configuration" ``` Signed records do not remove the need for code review. A valid signature proves which authorized identity produced a record; it does not prove that the change is wise or that a reviewer should merge it. Resolve Git conflicts --------------------- Treat each signed JSON record as an indivisible unit. Never splice signatures, policy fields, wrapped keys, ciphertext, or event content from both sides of a conflict: the resulting record will not verify, and mixing environment-key generations can make state unreadable. 1. Stop Ghostable writes and identify every unresolved path under `.ghostable/`. 2. Choose one complete, reviewed version of each conflicted record. For rotations, keep the policy, environment key metadata, grants, and values from the same authoritative generation. 3. Finish the merge or rebase, then rerun the discarded Ghostable operation from the resolved branch instead of recreating its JSON by hand. 4. Run status, validation, review, and a normal Git diff before committing the resolution. Inspect and verify a resolution Copy ``` $ git diff --name-only --diff-filter=U -- .ghostable $ ghostable status $ ghostable validate --env staging $ ghostable review $ git diff -- .ghostable ``` Abort when the authoritative generation is unclear If a conflict spans policy, access grants, environment keys, and values and you cannot identify one consistent generation, abort the merge or rebase and ask an active owner to replay the changes from a clean branch. Multiple checkouts ------------------ Ghostable registers one local identity against the project's canonical repository root. Opening the same project ID from a different checkout or worktree will require `ghostable access join` for that path instead of silently reusing the identity registered elsewhere. Treat the worktree as a separate device request, or perform Ghostable writes from the registered checkout and use the other worktree for code-only changes. On this page [ ![Ghostable](https://ghostable.dev/images/logo-dark.svg) ![Ghostable](https://ghostable.dev/images/logo-light.svg) ](https://ghostable.dev) CLI 3.x [ CLI 3.x ](https://ghostable.dev/docs/3.x) [ Desktop ](https://ghostable.dev/docs/desktop) CLI 3.x introduction Documentation local first no login encrypted repository plaintext hosted service Installation Documentation brew homebrew npm npx linux windows PATH version update Start a new project Getting Started setup seed dotenv owner initialize Adopt an existing project Getting Started existing env import authoritative source adopt Onboard a team member Getting Started join request approve roles offboarding pull request Repository and storage Core Concepts .ghostable git conflict merge worktree private identity metadata Environments Core Concepts protected production preview staging push sync pull replace run mask-output Variables and promotions Core Concepts var promote copy context annotation key Access and devices Core Concepts identity reader writer grantor owner revoke rotate leave delete Daily development workflow Workflows pull diff validate review clean daily Review and secret scanning Workflows scan sarif github suppress secrets drift Hygiene and rotation Workflows rotation stale unused suppression environment key Automation credentials Automation & CI GHOSTABLE\_CI\_TOKEN ci deploy credential powershell revoke replace Continuous integration Automation & CI GitHub Actions fork pull request JSON stdout stderr exit codes mask-output Deployments Automation & CI Forge Vapor Cloud provider CLI dry-run preserve remote keys temporary files Validation Reference schema required nullable regex min max different\_from Command reference Reference --help --json NO\_COLOR flags aliases exit code automation Configuration Reference ghostable.yaml activity mode auditEnvironments scan ignores deployTarget dotenv syntax Security Reference cryptography XChaCha20 Poly1305 HKDF user presence threat model Backups & Offline Reference recovery offline restore clone key identity Agent integration Reference AGENTS.md capabilities allowlist coding agent Troubleshooting Reference no project found revoked identity stale policy user presence invalid CI token provider CLI git conflict diagnostics Ghostable Desktop overview Desktop Installation Desktop Projects and setup Desktop Interface tour Desktop Environments and variables Desktop Local environment files Desktop Validation and review Desktop Activity Desktop Access and automation Desktop Project settings Desktop Application settings Desktop Licensing and updates Desktop Security and storage Desktop Troubleshooting Desktop No results found