Environment Variables

Sp00ky Cloud provides encrypted environment variable storage that syncs across your team. Each variable supports separate development and production values, so your local dev setup and production deployment stay in sync without .env files.

All values are encrypted at rest using the tenant’s Shared Vault. For details on the encryption model, key hierarchy, and security properties, see the vault documentation.

Quick Start

Bash

# 1. Initialize your encryption vault
spky cloud env init

# 2. Set a variable (interactive — prompts for value and environment)
spky cloud env set DATABASE_URL

# 3. Load variables and start your app
spky cloud env load && pnpm dev

Initializing the Vault

Before using environment variables, initialize your encryption vault:

Bash

spky cloud env init

You’ll be prompted to:

Choose a vault passphrase — this protects your encryption keys, pick something strong
Confirm the passphrase
Optionally cache it locally in ~/.sp00ky/vault-passphrase

If you skip env init, the vault will be created automatically the first time you run env set.

Teams

The first team member to run env init creates the tenant vault. Other members receive vault access through the invitation flow — they set their own passphrase when accepting the invitation. See Shared Vault for details.

Setting Variables

Bash

# With a name — goes straight to the value prompt
spky cloud env set DATABASE_URL

# Without a name — prompts for the name first
spky cloud env set

The CLI will interactively ask you:

Variable name (if not provided as argument)
Which environment(s) — choose from:
- Both (same value) — use one value for dev and prod
- Development only
- Production only
- Both (different values) — prompts for each separately
The value — entered with masked input (like a password prompt)

Variable names are automatically uppercased. Running env set on an existing variable updates only the environments you specify — it won’t overwrite the other environment’s value.

Loading Variables

Load environment variables and pipe them into your dev workflow:

Bash

# Load development variables (default) and start your app
spky cloud env load && pnpm dev

# Load production variables
spky cloud env load --prod && pnpm start

The output format is KEY=value, one per line — designed for shell evaluation:

Bash

# Export into the current shell
eval "$(spky cloud env load)"

# Or use with env
env $(spky cloud env load | xargs) pnpm dev

The first time you run env load, you’ll be prompted for your vault passphrase. You can choose to cache it locally so subsequent loads are automatic.

CI/CD Usage

In non-interactive environments (CI/CD), set the SPOOKY_API_KEY environment variable for authentication and cache the vault passphrase in ~/.sp00ky/vault-passphrase during your pipeline setup.

Listing Variables

Bash

spky cloud env list

Example output:

Bash

NAME                           DEV    PROD   UPDATED
-----------------------------------------------------------------
DATABASE_URL                   yes    yes    2026-04-08
STRIPE_SECRET_KEY              yes    yes    2026-04-08
DEBUG_MODE                     yes    -      2026-04-08

Values are never shown — only names and whether each environment has a value set.

Deleting Variables

Bash

spky cloud env delete DATABASE_URL

Importing from a File

Import variables from an .env file:

Bash

spky cloud env import .env

Supports standard .env format — one KEY=value per line, comments with #, and quoted values.

Passphrase Management

Changing your passphrase:

Bash

spky cloud env change-passphrase

Only your copy of the encryption key is re-wrapped. Other members and existing variables are unaffected.

Forgot your passphrase? A team admin can approve a reset so you can set a new one:

Bash

# Request a reset (admins are notified by email)
spky cloud vault request-reset

# After admin approves, set your new passphrase
spky cloud vault complete-reset

See Passphrase Reset for the full flow.

Caching: The CLI can cache your passphrase at ~/.sp00ky/vault-passphrase. To clear it:

Bash

rm ~/.sp00ky/vault-passphrase

CLI Reference

Bash

spky cloud env <COMMAND>

Commands:
  init               Initialize the encryption vault
  set [NAME]         Set an environment variable
  list               List all environment variable names
  load [--prod]      Load and output decrypted variables
  delete <NAME>      Delete an environment variable
  change-passphrase  Change your vault passphrase
  import <FILE>      Import variables from an .env file

spky cloud vault <COMMAND>

Commands:
  request-reset          Request a vault passphrase reset
  approve-reset <EMAIL>  Approve a pending reset (admin only)
  complete-reset         Set new passphrase after approval
  list-resets            List pending resets (admin only)

API Reference

All endpoints require authentication via Bearer token or API key.

Vault Endpoints

Initialize Vault

Bash

POST /v1/vault/init
Content-Type: application/json

{
  "passphrase": "your-vault-passphrase"
}

Returns 201 Created on success. Returns 409 Conflict if already initialized.

Vault Status

Bash

GET /v1/vault/status

JSON

{ "initialized": true }

Change Passphrase

Bash

POST /v1/vault/change-passphrase
Content-Type: application/json

{
  "current_passphrase": "old-passphrase",
  "new_passphrase": "new-passphrase"
}

Returns 401 with code invalid_passphrase if the current passphrase is wrong.

Passphrase Reset Endpoints

Request Reset

Bash

POST /v1/tenants/{tenantID}/vault-resets

Returns 201 Created. Sends email notification to all admins. Returns 409 Conflict if a request is already pending.

List Reset Requests (Admin)

Bash

GET /v1/tenants/{tenantID}/vault-resets

JSON

[
  {
    "id": "uuid",
    "account_id": "uuid",
    "email": "alice@example.com",
    "status": "pending",
    "expires_at": "2026-04-18T12:00:00Z",
    "created_at": "2026-04-11T12:00:00Z"
  }
]

Check Own Reset Status

Bash

GET /v1/tenants/{tenantID}/vault-resets/mine

Returns the current member’s active reset request, or 404 if none exists.

Approve Reset (Admin)

Bash

POST /v1/tenants/{tenantID}/vault-resets/{resetID}/approve
Content-Type: application/json

{
  "passphrase": "admin-vault-passphrase"
}

Returns 401 with code invalid_passphrase if the admin’s passphrase is wrong. Sends email to the requesting member.

Complete Reset

Bash

POST /v1/tenants/{tenantID}/vault-resets/complete
Content-Type: application/json

{
  "passphrase": "new-vault-passphrase"
}

Returns 404 if no approved reset exists. Passphrase must be at least 8 characters.

Cancel Reset

Bash

DELETE /v1/tenants/{tenantID}/vault-resets/{resetID}

Returns 204 No Content. Can be called by the requesting member or any admin.

Environment Variable Endpoints

All endpoints are scoped to a project: /v1/projects/{projectID}/envs.

Set Variable

Bash

PUT /v1/projects/{projectID}/envs/{NAME}
Content-Type: application/json

{
  "dev_value": "localhost:5432",
  "prod_value": "prod-host:5432",
  "both": false
}

dev_value and prod_value are optional — provide one or both
Set both: true with dev_value to use the same value for both environments
Variable names are stored uppercase
Returns 400 with code vault_not_initialized if the vault hasn’t been set up

List Variables

Bash

GET /v1/projects/{projectID}/envs

Returns variable names and metadata (no decrypted values):

JSON

[
  {
    "name": "DATABASE_URL",
    "has_dev": true,
    "has_prod": true,
    "updated_at": "2026-04-08T12:00:00Z"
  }
]

Load Variables (Decrypt)

Bash

POST /v1/projects/{projectID}/envs/load
Content-Type: application/json

{
  "passphrase": "your-vault-passphrase",
  "environment": "development"
}

environment accepts "development" (default) or "production"

JSON

{
  "variables": {
    "DATABASE_URL": "postgres://localhost:5432/myapp",
    "API_KEY": "sk_test_abc123"
  }
}

Returns 401 with code invalid_passphrase if the passphrase is wrong
Returns 400 with code vault_not_initialized if the vault hasn’t been set up

Delete Variable

Bash

DELETE /v1/projects/{projectID}/envs/{NAME}

Returns 204 No Content on success, 404 if the variable doesn’t exist.