How values are stored
Every value you set is encrypted with a sealed-box scheme before it hits the database. The encryption key never leaves the key-management layer, so a database dump contains only ciphertext. When fieldwick vars list or fieldwick env list runs, the API returns key names only - values are never included in list responses. To read a value you must call the single-key reveal endpoint, which is rate-limited to 10 requests per user per minute.
# List keys (no values returned)
fieldwick vars list my-api
# Reveal a single value (rate-limited: 10/user/min)
fieldwick vars list my-api --reveal --key DATABASE_URL
vars vs env - merge vs full-replace
Fieldwick has two variable groups and they behave differently on write. The vars group is a merge: each vars set call adds or overwrites individual keys and leaves all others untouched. The env group is a full-replace: when you pass --replace, every key not present in the new set is deleted. Use vars for day-to-day secrets you add incrementally. Use env when you want to declare the complete set authoritatively and have any stale key removed automatically.
# vars group - MERGE (safe to run any time, never deletes other keys)
fieldwick vars set my-api STRIPE_SECRET_KEY=sk_live_abc123
fieldwick vars set my-api REDIS_URL=redis://...
# env group - FULL-REPLACE (only the keys you list survive)
fieldwick env set my-api --replace \
DATABASE_URL=postgres://... \
STRIPE_SECRET_KEY=sk_live_abc123 \
REDIS_URL=redis://...
Setting, listing, and deleting
All three operations target a named service. Deleting a key triggers a redeploy of that service so the running container never holds a value that no longer exists in the store.
# Set one or more vars (merge)
fieldwick vars set my-api KEY=value ANOTHER=value2
# List all keys for a service
fieldwick vars list my-api
# Reveal a specific value
fieldwick vars list my-api --reveal --key STRIPE_SECRET_KEY
# Delete a key
fieldwick vars unset my-api STRIPE_SECRET_KEY
Importing from a .env file
You can pipe a .env file directly into the CLI. Keys that begin with the reserved prefixes FIELDWICK_, NOMAD_, and NIXPACKS_ are reserved for internal platform use and are rejected by default. Pass --force only if you genuinely need to override a platform variable and understand the side-effects.
# Import .env (reserved prefixes are rejected without --force)
fieldwick vars import my-api < .env
# Override rejection for reserved-prefix keys (use with care)
fieldwick vars import my-api --force < .env
Exporting and copying between services
Export writes key=value pairs to stdout in .env format so you can pipe directly into another service or save locally for auditing. Copying between services is a two-step pipe: export from the source, import to the target.
# Export all vars for a service (values revealed in output)
fieldwick vars export my-api > .env.backup
# Copy vars from one service to another
fieldwick vars export my-api | fieldwick vars import my-api-staging
Injecting vars into a one-off command
The fieldwick run command fetches a service's variables from the encrypted store, injects them into the child process environment, and then discards them - nothing is written to disk, to shell history, or to any file. This is the right way to run database migrations, seed scripts, or any one-off process that needs production credentials without leaving them in a file.
# Run a command with a service's vars injected (nothing written to disk)
fieldwick run -- npm start
# Target a specific service explicitly
fieldwick run --service my-api -- node scripts/migrate.js
# Run a database migration with production credentials
fieldwick run --service my-api -- npx prisma migrate deploy