Skip to content
GRIMOIRY

Store a shared secret

$ grim secrets:set GEOIP_API_KEY=abc123 --description="GeoIP lookups

The third time you paste the same API key into a new project's .env, it is time to store it once. A shared secret lives in the registry under a key, and grim install copies every one of them into the .env of the project it is setting up. A new colleague gets a working project without asking anyone for the GeoIP key.

Use it for credentials that are the same in every project of the team. What differs per project or per server does not belong here; that is what a project's own .env and grim env:set are for.

Usage

$ grim secrets:set GEOIP_API_KEY=abc123                               # store or replace
$ grim secrets:set GEOIP_API_KEY=abc123 --description="GeoIP lookups"   # with a note for the list
$ grim secrets:set "MAIL_FROM_NAME=Acme Shops"                        # quote it for your shell

It runs from anywhere and needs a login from grim auth:login, on an account the registry lets manage secrets. Inside a project whose grim.json sets registry_url, it writes to that registry.

Arguments and options

Set a shared secret in the GRIM registry

Usage

grim secrets:set [-d|--description DESCRIPTION] [--] <pair>

Arguments

Argument Description
pair KEY=VALUE pair (required)

Options

Option Description
-d, --description=DESCRIPTION Description of the secret

What it actually does

  1. Splits the pair at the first =. Both sides must be non-empty, so a secret cannot be set to nothing.
  2. Sends it to the registry with your token. A key that already exists is replaced, without a question. The description is sent only when you give one.
  3. Prints one line, ✓ Secret GEOIP_API_KEY followed by the status the registry answered with.

Nothing is written on your machine, and no project is touched.

How a secret reaches a project

Only through grim install. While it generates the project's configuration it fetches all shared secrets and writes each into .env: a line that already sets the key is overwritten with the registry's value, a missing key is added at the end.

Situation What happens to the project's .env
grim install in a new project Every shared secret is written in.
grim install run again later Every shared secret is written in again, over local edits of those keys.
You change a secret with secrets:set Nothing, until somebody runs grim install in that project.
Deployed servers Nothing, ever. A server's .env changes only through grim env:set or grim env:push.

Install fetches secrets quietly. Without a login, or without access, it skips them and says so only under -v. A fresh project with the shared keys missing usually means grim auth:login was never run on that machine.

Pitfalls

A local override does not survive install

If a project needs its own value under a key that is also a shared secret, the next grim install there puts the shared one back. Give the project's variable a different name, or take the key out of the registry.

Rotating a key is two jobs

secrets:set updates the registry and nothing else. Every project already installed and every server still holds the old value. Run grim install in the projects, and grim env:set for each deployed environment.

The value stays in your shell history

It is typed on the command line, so the shell saves it. Clear that line from the history afterwards when the secret matters.

The format is refused

Invalid format. Use: grim secrets:set KEY=VALUE means the = is missing, or one side of it is empty.

After it finishes

Check that it is there, under the name you meant.

$ grim secrets:list

grim secrets:list

See the shared secrets

Show which shared credentials the registry holds, by key and description, without ever showing a value.

grim secrets:delete

Remove a shared secret

Delete one credential from the registry so that future installs stop writing it into projects.

grim install

Assemble the whole project

Turn grim.json into a working project by fetching core, every module and theme, writing grim.lock, building the image and starting the stack.

grim auth:login

Log grim in to GitHub

Give grim a GitHub token, from your gh login or a personal access token, and hand the same token to Composer and Docker.

grim env:set

Change one server variable

Set a single KEY=VALUE in the .env of a deployed environment and recreate the containers so the app runs on it at once.

Recipes that use it

Change config on a live app

Set one value in a server's .env, confirm the app reads it, change many values through a pull and a push, rotate a secret the whole team shares, and apply an edit on a stack you run yourself.