Guidal
Sign in

Secrets

Store API keys, tokens and passwords so services can read them without exposing them.

Secrets hold values that must not be readable after they are set: API keys, signing keys, third-party tokens, passwords. They are set once and delivered to your services at runtime, but never printed back.

Setting a secret

Omit the value and you will be prompted, which keeps it out of your shell history:

bash
guidal secrets set STRIPE_API_KEY --service api

Listing

bash
guidal secrets list --service api

This shows secret names, never values. There is no command that prints a secret back — if you lose the value, set a new one.

Removing

bash
guidal secrets delete STRIPE_API_KEY --service api

Sharing a secret across services

Secrets can be linked to more than one service rather than duplicated:

bash
guidal secrets link SHARED_SIGNING_KEY --service worker
guidal secrets unlink SHARED_SIGNING_KEY --service worker

Linking means one value to rotate rather than several copies to keep in sync.

Importing many at once

bash
guidal secrets import .env.secrets --service api

Delete the file afterwards

An import file contains every secret in plain text. Remove it once the import succeeds, and never commit it — add it to .gitignore before you create it, not after.

Secrets versus environment variables

Both arrive in your application the same way, as environment variables. The difference is handling: secret values cannot be read back through the API, the CLI or the dashboard, and are not shown in logs or deploy output.

Use a secret whenever the value would be damaging to disclose. Use an environment variable otherwise — being able to read a log level back is genuinely useful.

When changes take effect

Like environment variables, secrets are read at container start. Redeploy for a change to reach the running process:

bash
guidal services deploy api

Rotation

To rotate, set the new value and redeploy:

bash
guidal secrets set STRIPE_API_KEY --service api
guidal services deploy api

If several services share the secret through linking, each still needs a redeploy to pick up the new value.