Pular para o conteúdo principal
informação
Esta página ainda não foi traduzida. Você está lendo a versão em English.

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]
envshed request --update <KEY> --reason "<why it is needed>" -e production,development [options]

Options​

OptionDescription
--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
--updateRotation 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-waitCreate the request and exit without waiting
--output jsonPrint a single JSON document for scripts and agents

Exit codes​

CodeStatusMeaning
0fulfilled, existsThe value is available. Use it with envshed run. With --update: every environment has a new value.
1overlap, rate_limitedError, 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
2pendingRequest is open (--no-wait only)
3declinedSomeone declined the request
4timeout, expiredStopped waiting, or the request expired on the server
5unusableThe 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​

  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.

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.

terminal
$ 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 -e is 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, changed and missing list 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 1 and status rate_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.