hostess secrets

Manage encrypted secrets for your Hostess projects — add, edit, delete, sync, and compare across environments.

Description

Manage secrets for your Hostess projects. Secrets are encrypted key-value pairs that are injected as environment variables at deploy time. This command group lets you add, edit, delete, retrieve, sync, and compare secrets across environments.

All secrets subcommands accept --token (or the HOSTESS_TOKEN environment variable via the same resolution order as other CLI commands).

For a conceptual overview of secrets, see the Secrets guide.

secrets get

Retrieve secrets for a project. Values are masked by default for security.

Usage

Terminal

hostess secrets get [names...] [flags]

Flags

Flag	Type	Default	Description
`--project`	`string`	From `hostess.yml`	Project slug
`--envs`	`string[]`	All environments	Environments to query (comma-separated or repeatable)
`--show-values`	`bool`	`false`	Reveal actual secret values
`--format`	`string`	`default`	Output format (`default` or `json`)
`--token`	`string`		Auth token

Examples

Terminal

# List all secrets (values masked)
hostess secrets get

Environment: production
--------------------------------------------------
KEY             | VALUE
--------------------------
JWT_SECRET      | ●●●●●●●●
STRIPE_API_KEY  | ●●●●●●●●
SENDGRID_KEY    | ●●●●●●●●

Environment: staging
--------------------------------------------------
KEY             | VALUE
--------------------------
JWT_SECRET      | ●●●●●●●●
STRIPE_API_KEY  | ●●●●●●●●

Terminal

# Get specific secrets with values revealed
hostess secrets get JWT_SECRET STRIPE_API_KEY --show-values

# Query only production
hostess secrets get --envs production

# Output as JSON
hostess secrets get --format json --show-values

# Get secrets for a specific project
hostess secrets get --project my-other-app

secrets add

Add a new secret to your project.

Usage

Terminal

hostess secrets add <name> [flags]

Flags

Flag	Type	Default	Description
`--value`	`string`	From `$NAME` env var	Secret value
`--project`	`string`	From `hostess.yml`	Project slug
`--envs`	`string[]`	All environments	Environments to add to (comma-separated or repeatable)
`--token`	`string`		Auth token

Examples

Terminal

# Add with explicit value
hostess secrets add JWT_SECRET --value "my-super-secret-key"

✓ Secret 'JWT_SECRET' added to production
✓ Secret 'JWT_SECRET' added to staging

Terminal

# Add from local environment variable
export STRIPE_KEY="sk_live_abc123"
hostess secrets add STRIPE_KEY

# Add to specific environments only
hostess secrets add STRIPE_KEY --value "sk_live_..." --envs production

# Add to a different project
hostess secrets add API_KEY --value "key123" --project my-other-app

If a secret with the same name already exists in an environment, add will skip it and suggest using secrets edit instead.

secrets edit

Update the value of an existing secret.

Usage

Terminal

hostess secrets edit <name> [flags]

Flags

Flag	Type	Default	Description
`--value`	`string`	From `$NAME` env var	New secret value
`--project`	`string`	From `hostess.yml`	Project slug
`--envs`	`string[]`	All environments	Environments to update (comma-separated or repeatable)
`--token`	`string`		Auth token

Examples

Terminal

# Update a secret value
hostess secrets edit JWT_SECRET --value "new-rotated-key"

✓ Secret 'JWT_SECRET' updated in production
✓ Secret 'JWT_SECRET' updated in staging

Terminal

# Update only in production
hostess secrets edit STRIPE_KEY --value "sk_live_new" --envs production

# Update from environment variable
export SENDGRID_KEY="SG.newkey..."
hostess secrets edit SENDGRID_KEY

For environments that need a new secret, use hostess secrets add; edit updates existing entries.

secrets delete

Remove a secret from your project.

Usage

Terminal

hostess secrets delete <name> [flags]

Flags

Flag	Type	Default	Description
`--project`	`string`	From `hostess.yml`	Project slug
`--envs`	`string[]`	All environments	Environments to delete from (comma-separated or repeatable)
`--token`	`string`		Auth token

Examples

Terminal

# Delete from all environments
hostess secrets delete OLD_API_KEY

✓ Secret 'OLD_API_KEY' deleted from production
✓ Secret 'OLD_API_KEY' deleted from staging

Terminal

# Delete from specific environments
hostess secrets delete TEST_KEY --envs preview,staging

secrets sync

Sync secrets between a local .env file and a remote Hostess environment.

Usage

Terminal

hostess secrets sync <push|pull> [flags]

The --env flag is required for sync operations — you must specify which environment to sync with.

Flags

Flag	Type	Default	Description
`--env`	`string`	Required	Target environment
`--file`	`string`	`.env`	Path to local .env file
`--project`	`string`	From `hostess.yml`	Project slug
`--token`	`string`		Auth token

Examples

Push — upload local .env to remote:

Terminal

# Push .env to production
hostess secrets sync push --env production

Sync Summary:
------------------------------
  Added:     5
  Updated:   2
  Unchanged: 0
------------------------------
  Total:     7 secrets synced

Terminal

# Push from a specific file
hostess secrets sync push --env staging --file .env.staging

Pull — download remote secrets to local file:

Terminal

# Pull production secrets to .env
hostess secrets sync pull --env production

✓ Pulled 12 secrets from production to .env

Terminal

# Pull to a specific file
hostess secrets sync pull --env staging --file .env.staging

When pulling, the local .env file will be overwritten. Make sure to back up any local-only values before running sync pull.

secrets diff

Compare secrets between two environments. Shows which secrets are only in one environment, which have different values, and which are identical.

Usage

Terminal

hostess secrets diff <env1> <env2> [flags]

Flags

Flag	Type	Default	Description
`--project`	`string`	From `hostess.yml`	Project slug
`--show-values`	`bool`	`false`	Reveal actual secret values in diff
`--format`	`string`	`default`	Output format (`default` or `json`)
`--token`	`string`		Auth token

Examples

Terminal

# Compare production and staging
hostess secrets diff production staging

Secret Diff: production vs staging
==================================================

Only in production (1):
  - PRODUCTION_ONLY_KEY = ●●●●●●●●

Only in staging (1):
  + DEBUG_MODE = ●●●●●●●●

Different values (1):
  STRIPE_KEY:
    production: ●●●●●●●●
    staging: ●●●●●●●●

Identical (3):
  = JWT_SECRET
  = SENDGRID_KEY
  = AWS_ACCESS_KEY_ID

Terminal

# Show actual values in the diff
hostess secrets diff production staging --show-values

# Output as JSON (useful for scripting)
hostess secrets diff production staging --format json

On this page