Getting Started

New Projects

Initialize Ghostable with a clean repository, define the first environments, and commit the encrypted project state your team will share.

Initialize interactively

Run setup from the project root:

Initialize Ghostable

$ ghostable setup

Setup asks for a project name and device label, creates a default environment, and detects an existing root .env. If one exists, you can import it immediately. The importing device becomes the first project owner.

Explicit team setup

For a reproducible non-interactive initialization, pass every decision as a flag:

Initialize a team project

$ ghostable setup --name "Acme API" --device-name "Jordan MacBook" --env default --env staging --env production --language php --framework laravel --package-manager composer --seed-dotenv --create-example --agent-instructions

--seed-dotenv imports the root .env into default. Additional initial environments receive their own keys but are not automatically given the default environment's values. Use env create --from-env or individual promotions to seed them intentionally.

Review generated files

Use status and Git to inspect the baseline before committing it:

Inspect the baseline

$ ghostable status
$ git status --short
$ ghostable validate --env default

The new .ghostable/ directory contains a manifest, signed policy, public device record, environment keys and grants, encrypted values, key metadata, and signed events. Your private device keys are stored outside the repository.

Commit the baseline

Commit Ghostable state

$ git add .ghostable .env.example AGENTS.md
$ git commit -m "Initialize Ghostable v3"

Review .ghostable/ diffs with the same care as application code. The values are encrypted, but device names, environment names, change reasons, annotations, and timestamps are intentionally visible metadata.

Create more environments

Create an empty environment, seed only its key layout, or copy non-sensitive values from an existing environment:

Create environments

$ ghostable env create preview --type preview
$ ghostable env create staging --type staging --from-env default --seed keys-only
$ ghostable env create production --type production --from-env staging --seed non-sensitive

Use --seed all only when copying every value is an intentional and reviewed decision.