Command Reference | Ghostable CLI 3.x

Top-level commands

ghostable setup: Initialize the project, owner device, policy, environments, keys, and optional .env import.
ghostable status: Show project, device, environment, and variable counts.
ghostable adopt: Generate a plain-text adoption prompt for schema, example, hygiene, drift, annotation, and CI work.
ghostable env: Manage environments and environment-level value workflows.
ghostable var: Manage one variable, promotion, encrypted context, and annotations.
ghostable validate: Validate stored or file-based values against schema rules.
ghostable schema: Manage schema files, rules, and keys.
ghostable review: Review changed-code ENV usage and hard-coded secrets.
ghostable scan: Compatibility alias for hard-coded secret scanning; prefer review --secrets-only.
ghostable example: Generate or update .env.example from encrypted state and code references.
ghostable hygiene: Report operational findings, configure rotation rules, suppress findings, and rotate environment keys.
ghostable access: Manage devices, requests, roles, and automation credentials.
ghostable device: Alias for human-device access operations.
ghostable deploy: Write a local env file or sync values to a supported provider.
ghostable agent: Emit agent guidance and the recommended safe capability list.

Command help

$ ghostable --help
$ ghostable env --help
$ ghostable env pull --help

The installed command's --help output is authoritative for flags and formats in that release. This page maps the stable command families instead of duplicating every flag.

Environment commands

env list: List environment names, types, variable counts, and last update times.
env create [name]: Create an environment with optional --type, --from-env or --from-file, and --seed mode.
env push: Create or update values from an env file without deleting absent stored keys.
env sync: Push a file and delete stored keys that are absent from it.
env pull: Merge or replace a local env file; backs up an existing file by default.
env clean: Preview or remove project-root .env and .env.* files, keeping examples by default.
env run: Inject values into one child command without writing an env file.
env shell: Open a shell with injected values.
env diff: Compare a stored environment to a file, or compare two stored environments.
env history: Show signed events filtered by environment, key, action, or limit.
env rename: Rename an environment and its repository-backed state.
env delete: Delete an environment after confirmation.
env duplicate <source> <target>: Advanced shortcut to create and seed a copy using keys-only, non-sensitive, or all.
env layout generate: Advanced command that writes sparse key ordering metadata from stored keys or a file.
env file save: Integration command that atomically saves base64-encoded env content inside the project with restrictive permissions.

Variable commands

var push: Save one key from a file or an interactive secret prompt.
var pull: Write one key to a file or explicitly print it with --show-values.
var promote: Copy a value or key-only layout from one environment to another; var copy is an alias.
var delete: Delete one stored variable with an optional signed reason.
var history: Show signed history using the environment-history filters.
var context: Read or replace an encrypted note associated with one key.
var annotation list: List plaintext typed annotations for a key.
var annotation set: Set exactly one --string, --number, or --bool annotation value.
var annotation remove: Remove one annotation by name.
var enable / disable: Advanced commands that control active versus commented env-file output.
var status: Advanced explicit status command using --enabled, --disabled, or --commented.

Access commands

access join: Create a local device identity and public repository record for this checkout.
access status: Show the current device, local identity path, roles, and permissions.
access list: List project device records.
access approvers: Show devices allowed to grant access for an environment.
access requests list: List pending requests; --all includes reviewed and already-granted requests.
access requests create: Request reader, writer, grantor, or owner access for one environment or all.
access requests approve / deny: Review a signed request by request ID.
access share: Directly grant a role to a device for an environment or all.
access grants: Advanced list of environment grant records.
access matrix: Advanced role matrix by device and environment.
access create: Create a scoped ci, deploy, or access automation credential.
access revoke: Permanently revoke an identity; --env controls which grants are removed and which environment keys rotate automatically.
access leave: Remove this machine's local access; the last owner cannot leave.
access cleanup: Preview or remove orphaned local identities.
access delete: Delete an already-revoked public device record.

Validation and review

validate: Validate --env stored values or a supplied --file; supports --json.
schema rule add / remove / update: Mutate rules in the global or selected schema file.
schema key rename / remove: Rename or remove a schema key.
schema file save / delete: Advanced integration commands for base64 schema content and safe deletion.
review [run]: Review ENV drift and secrets for the selected paths and Git range.
review suppress: Create a signed, scoped, optionally expiring finding suppression.
scan [run]: Run only the compatibility hard-coded secret scanner.
scan suppress: Create a signed secret-scan suppression.
example generate: Create or update an example file using blank, non-sensitive, or all value mode.

Hygiene and deployment

hygiene report: Report rotation, environment-key age, and optional stale or unused findings.
hygiene rotation list / set / remove: Manage project and environment-specific variable rotation rules.
hygiene suppress: Create a signed hygiene exception by code and optional env/key scope.
hygiene rotate: Inspect or rotate an environment encryption key.
deploy [environment]: Replace a local .env by default; supports --merge, --backup, --only, and --dry-run.
deploy local: Force local env-file output when the manifest has a provider target.
deploy laravel-forge: Sync selected values with the Forge CLI; forge is an alias.
deploy laravel-vapor: Sync values with the Vapor CLI; vapor is an alias.
deploy laravel-cloud: Set selected values with the Cloud CLI; cloud is an alias.

Agent and advanced commands

agent instructions: Print the recommended Ghostable rules for coding agents.
agent capabilities: List the safe default agent command allowlist; supports --json.
agent init: Write Ghostable guidance to AGENTS.md; --dry-run prints without writing.
adopt --all --ci: Generate a broad project-adoption prompt including optional CI recommendations.
setup --agent-instructions: Initialize the project and add agent guidance in one workflow.

Commands omitted from the standard interactive menus are advanced integration surfaces. Prefer the documented primary workflow unless Desktop or another controlled tool requires them.

Automation contract

--json: Available only on commands that advertise it in --help. Writes one machine-readable result to stdout.
--format github: Review-only workflow annotations suitable for GitHub Actions logs.
--sarif: Hygiene-report output for code-scanning systems. Do not combine it with --json.
stderr: Receives usage, verification, runtime, and final failure messages. Keep it separate from structured stdout.
Exit 0 / 1 / 130: Success or passed checks / usage, runtime, verification, or validate, review, and scan finding failure / canceled prompt. Hygiene reports findings without failing by default; env run preserves a child failure code.

A failed validation still emits a complete result on stdout before exiting non-zero:

{
  "environment": "staging",
  "passed": false,
  "errors": [
    {
      "key": "APP_URL",
      "rule": "url",
      "message": "must be a valid URL"
    }
  ]
}

Pin the CLI version used by an integration and ignore unknown JSON fields so additive output does not break it. Structured output is not automatically safe to publish: access create --json intentionally includes the newly created credential token, and flags that explicitly reveal values remain sensitive.

Automation conventions

Use --json for structured output where offered.
Repeat list flags or pass comma-separated values, such as --only APP_KEY,DATABASE_URL.
Pass --reason for writes, promotions, deletions, and rotations.
Use --assume-yes or -y only after a script has fully resolved its target.
Set the standard NO_COLOR environment variable to disable ANSI styling.
Use ghostable --version to record the CLI release in diagnostics.