envshed request
Ask a person to provide a secret. The value goes straight into Envshed, so it never passes through this terminal or the chat of an AI agent. The command waits for an answer and reports only the key and the status.
Usage
envshed request <KEY> --reason "<why it is needed>" [options]
envshed request --update <KEY> --reason "<why it is needed>" -e production,development [options]
Options
| Option | Description |
|---|---|
--reason <text> | Required. Why the secret is needed, shown to whoever fills it. Do not put a secret here. |
-o, --org <slug> | Organization slug |
-p, --project <slug> | Project slug |
-e, --env <slug> | Environment slug. With --update, several slugs separated by commas, for example production,development |
--update | Rotation request: ask for a new value for a key that already has one. See Rotation requests. |
--timeout <duration> | How long to wait, such as 90s, 10m or 1h. Default: 10m. |
--no-wait | Create the request and exit without waiting |
--output json | Print a single JSON document for scripts and agents |
Exit codes
| Code | Status | Meaning |
|---|---|---|
0 | fulfilled, exists | The value is available. Use it with envshed run. With --update: every environment has a new value. |
1 | overlap, rate_limited | Error, such as no access or an invalid option. With --update, overlap: an open rotation request already covers some of these environments, or rate_limited: too many rotation requests for this key in the last hour |
2 | pending | Request is open (--no-wait only) |
3 | declined | Someone declined the request |
4 | timeout, expired | Stopped waiting, or the request expired on the server |
5 | unusable | The key exists as a placeholder or is disabled, so envshed run cannot use it. With --update: the key has no value to rotate in one of the environments |
What happens
- The command opens a request and prints a dashboard link and the matching
envshed secret setcommand. - People who can fill it see it in the notification bell of the project.
- Someone saves the value on the request page, or sets the key by any other route, such as
envshed secret setorenvshed push. - The command exits with
0and tells you to useenvshed run. The value is never printed.
$ envshed request GITHUB_PAT --reason "configure the runner" -e development
Requested GITHUB_PAT.
Fill it in the dashboard:
https://app.envshed.com/acme/web/requests/6f1c...
Or in a separate terminal (not in an agent chat):
envshed secret set GITHUB_PAT -o acme -p web -e development
GITHUB_PAT is ready. The value was not printed.
Use it with: envshed run -e development -- <command>
Behavior
- Existing keys are never overwritten. If the key already has a value, the command says so and exits with
0. - Re-running is safe. Running the command again for a key with an open request attaches to that request. Use this after a timeout or when a tool limits how long a command can run.
- Requests expire. An unanswered request closes after 7 days.
- A decline sticks for an hour. Asking again for the same key within that hour returns the decline instead of notifying people again.
- Limit. Each environment can have 20 open requests.
Rotation requests
Use --update when the key already has a value and someone has to replace it: a leaked or expiring credential, a placeholder value, or a token that must change in several environments at once. The request page never shows the current value.
$ envshed request --update COOLIFY_TOKEN -e production,development \
--reason "New token only for SST, created in the Coolify panel"
Requested a new value for COOLIFY_TOKEN in production, development.
Enter the new value in the dashboard (the request does not display the current value):
https://app.envshed.com/acme/web/requests/6f1c...
Or in a separate terminal (not in an agent chat):
envshed secret set COOLIFY_TOKEN -o acme -p web -e production
envshed secret set COOLIFY_TOKEN -o acme -p web -e development
COOLIFY_TOKEN has a new value in every environment. The value was not printed.
- One request, several environments. All environments must belong to the project and have a value for the key. The first one in
-eis where the request lives. - Done only when every environment changed. An environment counts as changed when a new value is saved on the request page or by any other route (
envshed secret set, an edit in the dashboard) after the request was made. While some environments are still waiting, the request stays open and the command reports which changed and which are missing. With--output json,changedandmissinglist the environment slugs. - Links are followed. Saving on the request page writes the value where it lives: an environment that uses a linked value changes its source, and every environment of the link gets the new value. The page lists those environments before saving, and the change appears in Recent changes as "Changed through a rotation request".
- Re-running is safe. The same key and environments attach to the open request. A request that covers only some of them is reported as
overlap. - A closed request is never reused. After a rotation request is declined, completed or expired, asking again creates a new one.
- Limit per person. One person or token can open 3 rotation requests for the same key in a project per hour; completed ones do not count. Past that, the command exits with
1and statusrate_limited. - Who can respond. People with permission to edit the environments. On the dashboard, the person asking can also pick an org member to receive the request; only members who can edit every selected environment are offered.
Permissions
Asking needs read access to the environment, so a viewer or a read-only service token can ask. Asking grants nothing: if you could not read the environment before, the command fails, and a viewer still cannot change a secret.
Org owners and admins, and project admins and editors with access to the environment, can fill or decline. Read-write service tokens can too.
Each step is recorded in the audit log: who asked and why, who filled or declined, and when. For a rotation request, also which environments changed. Values are never logged.
Limits
This protects against accidental leaks. It does not stop an agent with shell access from reading a value that it can already reach, for example by running envshed run -- printenv.