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

terminal

envshed request <KEY> --reason "<why it is needed>" [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
--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.
1		Error, such as no access or an invalid option
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

What happens

1. The command opens a request and prints a dashboard link and the matching envshed secret set command.
2. People who can fill it see it in the notification bell of the project.
3. Someone saves the value on the request page, or sets the key by any other route, such as envshed secret set or envshed push.
4. The command exits with 0 and tells you to use envshed run. The value is never printed.

terminal

$ 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.

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. 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.