agent-secrets CLI

agent-secrets is the command an agent session runs to use a secret; agent-secrets-helper is the per-user daemon that signs for a host’s agent sessions. This page is their own help.

agent-secrets

usage:
  agent-secrets keygen --out <dir>
      Write a new signing key to <dir>/key.pem and print its thumbprint. A box's launcher runs it
      inside the box before enrolling it.
  agent-secrets enroll --helper --runtime-id <id> --thumbprint <tp> [--session-id <id>] | --pod --service <name> [--pod-token-file <file>] [--out <dir>]
      Enroll a session key a launcher holds (a box's) through this machine's agent-secrets-helper,
      or, with --pod, enroll this Kubernetes pod itself, for the broker-side service --service
      names: a pod proves who it is with the projected service-account token its own kubelet
      mounts (--pod-token-file, default /var/run/legion/agent-secrets-token/token).
      Each writes the enrollment id to AGENT_SECRETS_KEY_DIR/enrollment and prints it, alone, on
      stdout. --pod also writes key.pem there, reusing the one already in --out: a re-run keeps
      that key's enrollment and renews its lease, and runs on one directory take turns. A pod keeps
      its own lease alive with the command --pod prints, which names the key directory because renew
      reads AGENT_SECRETS_KEY_DIR and never --out:
      `AGENT_SECRETS_KEY_DIR=<dir> agent-secrets renew --pod-token-file <file>`.
  agent-secrets unenroll --helper --enrollment <id>
      End an enrollment `enroll --helper` made, through this machine's agent-secrets-helper.
  agent-secrets machine login
      Log this machine in: print the confirmation code its operator types into Dispatch, then wait
      for the decision (exit 0 once approved, 1 when denied or expired).
  agent-secrets machine login-status
      Print "issued" and exit 0 while this machine's helper holds a launcher credential; otherwise
      print the last login's state and exit 1.
  agent-secrets machine list [--json]
      List your own machines' logins that can still reach a secret, under this machine's login:
      each one's id, host, who approved it, when it was issued and expires, and whether it has
      expired with sessions still running. Dispatch's machine-login page lists the same, and every
      service's login beside them.
  agent-secrets machine revoke <credential_id>
      End one of your own machines' logins under this machine's login, as Dispatch's machine-login
      page does: it enrolls nothing more, and every session it enrolled ends. Revoking this
      machine's own login ends this machine's broker access too.
  agent-secrets grant list [--json]
      List the live grants of your sessions and those you approved, under this machine's login:
      each one's id, secrets, how it was granted, who approved it, who decided it (the model judge
      for a grant it approved), its session and operator, and when it expires. Dispatch's Live
      grants page lists the same.
  agent-secrets grant revoke <grant_id>
      End a grant as its operator or approver, under this machine's login, as Dispatch's Live
      grants page does. Ending an automatic grant also makes its session ask before it gets those
      secrets again.
  agent-secrets login
      Sign in on this machine as yourself: print the code to type in at Google, then record the
      sign-in at the secrets broker, which binds it to a box key this machine makes. Every session
      of yours on this machine then acts as you. A second person signs in beside you, and
      AGENT_SECRETS_PERSON then says which of you a session acts for.
  agent-secrets register [--wait SECONDS] [--session-id ID] [--exec -- COMMAND [ARGS...]]
      Register this process with agent-secrets-helper as a machine session. With --exec, run COMMAND
      as this same process, so it and everything it starts are that session. With --session-id, the
      session keeps one broker identity — and the requests and grants bound to it — across a restart
      of the helper or of the machine, rather than enrolling afresh as a new pid; run it again with
      the id from inside a session that could not name one at launch.
  agent-secrets identity
      Exit 0 when this process has a broker identity and 1 when it does not, asking the broker
      nothing.
  agent-secrets --version
      Print the release this binary was built as.
  agent-secrets renew [--pod-token-file FILE]
      Keep an agent box's or pod's enrollment lease alive, renewing it until interrupted. A pod
      names its projected service-account token's file, read again before each renewal, so each
      renewal sends the token of that moment, which the broker checks names the pod the enrollment
      was made for. POD_TOKEN_REQUIRED, ENROLLMENT_NOT_LIVE, or an older broker's PROOF_INVALID
      saying "not live" exits 76, naming the enrollment, HTTP status and broker code; every other
      refusal retries.
  agent-secrets request NAME... [--reason TEXT] [--ttl DURATION] [--json]
      Request secrets and print the request's id, state and source, the broker's own detail when
      it denied them, and who approves it and where while it waits; exit 75 while it waits for
      approval and 77 when it is denied. A name a person must approve needs
      --reason; with none the whole request is denied. The
      grant lasts --ttl, or 15 minutes when any secret is human tier and 12 hours
      otherwise (until this session ends when every secret is tagged
      default-grant=session).
  agent-secrets status <request_id> [--json]
      Print a request's state, the broker and store it is at, who approves it and where while it
      waits, its grant once granted, who decided it, and the broker's own detail when it was
      denied.
  agent-secrets cancel <request_id>
      Cancel one of this session's pending requests.
  agent-secrets revoke <grant_id>
      End one of this session's grants.
  agent-secrets self [--json]
      Print this session's enrollment, operator, lease, live grants, and the broker and store
      every secret of this session comes from.
  agent-secrets whoami [--json]
      Print this session's enrollment as the broker's JSON, as self --json does.
  agent-secrets sign --method M --url U [--enrollment E]
      Print the proof this session would sign for one broker call, without making the call.
  agent-secrets secret list [--json] [--profile P]
      List every agent secret, under the environment's cloud credential: its name, owner, tier, kind,
      shape, max grant, default grant, whether it has a value, and its deletion once it is deleted,
      with the earliest purge beside it on Secrets Manager; --json also prints each one's store,
      secret name, github-owners, requesters, scopes and admin mark, and its created and
      last-changed times where the store gives them. Name the store the rows are in.
  agent-secrets secret show NAME [--json] [--profile P]
      Print an agent secret's name, store, secret name, owner, tier, kind, github-owners,
      requesters, scopes, admin mark, shape, max grant, default grant, its created and
      last-changed times, its deletion once it is deleted, with the earliest purge beside
      it on Secrets Manager, and its versions; --json prints those and whether it has a value.
      Never print its value.
  agent-secrets secret create NAME --owner me|shared|EMAIL --tier agent|human [--kind github-app|google-login|azure-login|google-service-account|none] [--github-owners LOGINS] [--requesters LIST] [--scopes LIST] [--admin true] [--shape token|document] [--max-grant DURATION] [--default-grant session] [--profile P]
      Create an agent secret under the environment's cloud credential, then ask the broker to serve it.
      --owner me is the email of the person that credential names, and is refused where it names
      none; --owner EMAIL names the owning person by email. Read its value from standard input, or
      type it at a prompt with echo off.
  agent-secrets secret set NAME [--profile P]
      Set a new agent-secret value under the environment's cloud credential. Then ask the broker to
      serve it. Read the value from standard input, or type it at a prompt with echo off.
  agent-secrets secret retag NAME [--owner me|shared|EMAIL] [--tier agent|human] [--kind github-app|google-login|azure-login|google-service-account|none] [--github-owners LOGINS|none] [--requesters LIST|none] [--scopes LIST|none] [--admin true|none] [--shape token|document|none] [--max-grant DURATION|none] [--default-grant session|none] [--profile P]
      Change an agent secret's owner, tier, kind, GitHub owners, requesters, scopes, admin mark,
      shape, max grant or default grant under the environment's cloud credential. Then ask the broker
      to reread it. none removes a kind, GitHub owners, requesters, scopes, the admin mark, a shape, a
      max grant or a default grant, in a retag of its own. An administrator changes a shared secret's
      owner and tier. This CLI cannot tell whether a requesters entry naming a service is one the
      deployment registers: it holds no list of them, so the broker's answer to the reread is what
      catches an unregistered name, printing its refusal and its reason, and the retag exits 1 with
      the tag written.
  agent-secrets secret delete NAME [--profile P]
      Schedule the agent secret NAME's deletion, restorable for 30 days, under the environment's
      cloud credential, then ask the broker to stop serving it at once.
  agent-secrets secret restore NAME [--profile P]
      Cancel the agent secret NAME's scheduled deletion under the environment's cloud credential,
      then ask the broker to serve it again at once.
  agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] [--github-owner LOGIN [--github-repo NAME]... [--github-read-only]] [--github-token] -- <command> [args...]
      Request secrets, wait up to --wait (default 30m) for a person to decide, and run <command>
      with each granted secret in its environment under its NAME; nothing runs unless all are
      granted. One line on stderr names those secrets and the broker and store they came from,
      never a value. A name a person must approve needs --reason; with none the
      whole request is denied. The grant lasts --ttl, or 15 minutes when any secret is human tier and 12 hours otherwise (until this session ends when every secret is tagged default-grant=session). --github-owner narrows each
      GitHub App token the grant releases to that account's installation, and --github-repo and
      --github-read-only narrow it further, to those repositories and to read access; a token
      narrowed to repositories alone keeps every permission the App holds, so a machine that must
      only read needs --github-read-only too. <command> runs only once the broker answers that it
      applied the narrowing. Each GitHub App secret's NAME holds the JSON object of installations
      the release makes; with --github-token it holds that one installation's token alone, which is
      the form a command that sends the token to GitHub needs. --github-token needs --github-owner,
      and nothing runs when a release holds other than one installation, or when the grant releases
      no GitHub App token at all.

environment:
  AGENT_SECRETS_URL          the broker's base URL; every form that calls the broker needs it
  AGENT_SECRETS_KEY_DIR      an agent box's or pod's key.pem and enrollment
                             (default $XDG_RUNTIME_DIR/agent-secrets, used when key.pem is there)
  AGENT_SECRETS_HELPER_SOCK  a machine session's agent-secrets-helper socket
  AGENT_SECRETS_ENROLL_WAIT  how long a call waits while a box's launcher is still enrolling it
                             (default 20s)
  AGENT_SECRETS_APPROVE_URL  Dispatch's address; machine login names the page under it where the
                             operator types the code
  OMP_SESSION_ID             the agent session the broker names and notifies if a pending request
                             expires; falls back to ENVOY_SESSION_ID, then CLAUDE_CODE_SESSION_ID,
                             so a harness that sets one of those instead still names its session
  AGENT_SECRETS_PERSON       which person a session acts for, where more than one has signed in
                             on this machine with agent-secrets login; with one sign-in it is
                             that person, and with more and this unset every form that needs a
                             session identity refuses and names them
  AGENT_SECRETS_SIGNIN_DIR   where agent-secrets login keeps this machine's sign-ins
                             (default $XDG_STATE_HOME/agent-secrets/signins, which a reboot
                             keeps; the key dir above is runtime state and does not)
  AGENT_SECRETS_SIGNIN_CLIENT_ID
                             the device-flow client agent-secrets login signs a person in as
  AGENT_SECRETS_SIGNIN_CLIENT_SECRET_FILE
                             a file holding that client's secret
  AGENT_SECRETS_SIGNIN_ISSUER
                             where a person signs in (default https://accounts.google.com); a dev
                             stack names its own issuer
  AGENT_SECRETS_MACHINE_IDENTITY
                             the identity this machine proves at the broker's token exchange,
                             which a person's sign-in presents as the actor token: kubernetes
                             (AGENT_SECRETS_MACHINE_TOKEN_FILE), metadata
                             (AGENT_SECRETS_MACHINE_AUDIENCE) or pool (both, with
                             AGENT_SECRETS_POOL_AUDIENCE and AGENT_SECRETS_POOL_ACCOUNT)
  AGENT_SECRETS_MACHINE_TOKEN_FILE
                             this machine's projected Kubernetes service-account token
  AGENT_SECRETS_MACHINE_AUDIENCE
                             the audience of this machine's Google identity token
  AGENT_SECRETS_POOL_AUDIENCE
                             the workload identity pool provider an external credential is
                             traded at, the full //iam.googleapis.com/projects/... resource name
  AGENT_SECRETS_POOL_ACCOUNT the managed identity generateIdToken is called on
  AGENT_SECRETS_SESSION      the session name a trade writes under, where the deployment's entry
                             fixes none
  AWS_PROFILE                the AWS profile the secret forms sign in with when --profile names
                             none (else the AWS SDK's default credential chain); every secret
                             form needs a sign-in in the broker's account, and the store's IAM
                             decides what it may do there
  CLOUDSDK_AUTH_ACCESS_TOKEN a Google access token the secret forms sign in with against a broker
                             on Google Cloud, before the Application Default Credentials and the
                             gcloud login; the store's IAM decides what it may do

exit codes: 0 done, 1 failed, 2 usage error, 75 still waiting for approval, 76 permanent renewal refusal, 77 denied;
register --exec exits 127 when COMMAND is not found and 126 when it cannot run;
secret create and set end by the signal on hang-up (SIGHUP), interrupt (Ctrl-C), quit (Ctrl-\)
or termination (SIGTERM) at the value prompt: a shell reports 129, 130, 131 or 143

agent-secrets keygen

usage: agent-secrets keygen --out <dir>

Write a new signing key to <dir>/key.pem and print its thumbprint. A box's launcher runs it
inside the box before enrolling it.

flags:
  -out string
      directory to write key.pem into

agent-secrets enroll

usage: agent-secrets enroll --helper --runtime-id <id> --thumbprint <tp> [--session-id <id>] | --pod --service <name> [--pod-token-file <file>] [--out <dir>]

Enroll a session key a launcher holds (a box's) through this machine's agent-secrets-helper,
or, with --pod, enroll this Kubernetes pod itself, for the broker-side service --service
names: a pod proves who it is with the projected service-account token its own kubelet
mounts (--pod-token-file, default /var/run/legion/agent-secrets-token/token).
Each writes the enrollment id to AGENT_SECRETS_KEY_DIR/enrollment and prints it, alone, on
stdout. --pod also writes key.pem there, reusing the one already in --out: a re-run keeps
that key's enrollment and renews its lease, and runs on one directory take turns. A pod keeps
its own lease alive with the command --pod prints, which names the key directory because renew
reads AGENT_SECRETS_KEY_DIR and never --out:
`AGENT_SECRETS_KEY_DIR=<dir> agent-secrets renew --pod-token-file <file>`.

flags:
  -helper
      enroll through this machine's agent-secrets-helper, which holds its launcher credential (required without --pod: a launcher credential is a key held only by a helper or a launcher, never a token this CLI could read)
  -out string
      --pod: the directory holding key.pem and enrollment; AGENT_SECRETS_KEY_DIR when not given
  -pod
      enroll this Kubernetes pod with the projected service-account token its own kubelet mounts
  -pod-token-file string
      --pod: a pod's projected service-account token file (default "/var/run/legion/agent-secrets-token/token")
  -runtime-id string
      this runtime's stable id
  -service string
      --pod: the broker-side service this pod's service account is bound to
  -session-id string
      the agent session the broker notifies if one of this session's pending requests expires
  -thumbprint string
      the signing key's RFC 7638 thumbprint

agent-secrets unenroll

usage: agent-secrets unenroll --helper --enrollment <id>

End an enrollment `enroll --helper` made, through this machine's agent-secrets-helper.

flags:
  -enrollment string
      the enrollment id to revoke
  -helper
      unenroll through the local agent-secrets-helper socket

usage: agent-secrets machine login

Log this machine in: print the confirmation code its operator types into Dispatch, then wait
for the decision (exit 0 once approved, 1 when denied or expired).

usage: agent-secrets machine login-status

Print "issued" and exit 0 while this machine's helper holds a launcher credential; otherwise
print the last login's state and exit 1.

agent-secrets machine list

usage: agent-secrets machine list [--json]

List your own machines' logins that can still reach a secret, under this machine's login:
each one's id, host, who approved it, when it was issued and expires, and whether it has
expired with sessions still running. Dispatch's machine-login page lists the same, and every
service's login beside them.

flags:
  -json
      print the broker's response body verbatim

agent-secrets machine revoke

usage: agent-secrets machine revoke <credential_id>

End one of your own machines' logins under this machine's login, as Dispatch's machine-login
page does: it enrolls nothing more, and every session it enrolled ends. Revoking this
machine's own login ends this machine's broker access too.

agent-secrets grant list

usage: agent-secrets grant list [--json]

List the live grants of your sessions and those you approved, under this machine's login:
each one's id, secrets, how it was granted, who approved it, who decided it (the model judge
for a grant it approved), its session and operator, and when it expires. Dispatch's Live
grants page lists the same.

flags:
  -json
      print the broker's response body verbatim

agent-secrets grant revoke

usage: agent-secrets grant revoke <grant_id>

End a grant as its operator or approver, under this machine's login, as Dispatch's Live
grants page does. Ending an automatic grant also makes its session ask before it gets those
secrets again.

usage: agent-secrets login

Sign in on this machine as yourself: print the code to type in at Google, then record the
sign-in at the secrets broker, which binds it to a box key this machine makes. Every session
of yours on this machine then acts as you. A second person signs in beside you, and
AGENT_SECRETS_PERSON then says which of you a session acts for.

agent-secrets register

usage: agent-secrets register [--wait SECONDS] [--session-id ID] [--exec -- COMMAND [ARGS...]]

Register this process with agent-secrets-helper as a machine session. With --exec, run COMMAND
as this same process, so it and everything it starts are that session. With --session-id, the
session keeps one broker identity — and the requests and grants bound to it — across a restart
of the helper or of the machine, rather than enrolling afresh as a new pid; run it again with
the id from inside a session that could not name one at launch.

flags:
  -exec
      after registering, exec the command that follows as this same process
  -session-id string
      the omp session id this session keeps its broker identity under, across a restart of the helper or the machine
  -wait int
      wait up to this many seconds for the helper to enroll the session (0 returns at once, as does a helper holding no launcher credential)

agent-secrets identity

usage: agent-secrets identity

Exit 0 when this process has a broker identity and 1 when it does not, asking the broker
nothing.

agent-secrets renew

usage: agent-secrets renew [--pod-token-file FILE]

Keep an agent box's or pod's enrollment lease alive, renewing it until interrupted. A pod
names its projected service-account token's file, read again before each renewal, so each
renewal sends the token of that moment, which the broker checks names the pod the enrollment
was made for. POD_TOKEN_REQUIRED, ENROLLMENT_NOT_LIVE, or an older broker's PROOF_INVALID
saying "not live" exits 76, naming the enrollment, HTTP status and broker code; every other
refusal retries.

flags:
  -pod-token-file string
      a pod's projected service-account token file, read again before every renewal

agent-secrets request

usage: agent-secrets request NAME... [--reason TEXT] [--ttl DURATION] [--json]

Request secrets and print the request's id, state and source, the broker's own detail when
it denied them, and who approves it and where while it waits; exit 75 while it waits for
approval and 77 when it is denied. A name a person must approve needs
--reason; with none the whole request is denied. The
grant lasts --ttl, or 15 minutes when any secret is human tier and 12 hours
otherwise (until this session ends when every secret is tagged
default-grant=session).

flags:
  -json
      print the response body verbatim
  -reason string
      why these secrets are needed; necessary where a person approves
  -ttl duration
      how long the grant lasts, a whole number of seconds such as 2m or 90s; unset, it lasts 15 minutes when any secret is human tier and 12 hours otherwise, or until this session ends when every secret is tagged default-grant=session

agent-secrets status

usage: agent-secrets status <request_id> [--json]

Print a request's state, the broker and store it is at, who approves it and where while it
waits, its grant once granted, who decided it, and the broker's own detail when it was
denied.

flags:
  -json
      print the response body verbatim

agent-secrets cancel

usage: agent-secrets cancel <request_id>

Cancel one of this session's pending requests.

agent-secrets revoke

usage: agent-secrets revoke <grant_id>

End one of this session's grants.

agent-secrets self

usage: agent-secrets self [--json]

Print this session's enrollment, operator, lease, live grants, and the broker and store
every secret of this session comes from.

flags:
  -json
      print the response body verbatim

agent-secrets whoami

usage: agent-secrets whoami [--json]

Print this session's enrollment as the broker's JSON, as self --json does.

flags:
  -json
      print the response body verbatim

agent-secrets sign

usage: agent-secrets sign --method M --url U [--enrollment E]

Print the proof this session would sign for one broker call, without making the call.

flags:
  -enrollment string
      sign for this enrollment id instead of this process's own (file mode only)
  -method string
      HTTP method of the call
  -url string
      absolute URL of the call

agent-secrets secret list

usage: agent-secrets secret list [--json] [--profile P]

List every agent secret, under the environment's cloud credential: its name, owner, tier, kind,
shape, max grant, default grant, whether it has a value, and its deletion once it is deleted,
with the earliest purge beside it on Secrets Manager; --json also prints each one's store,
secret name, github-owners, requesters, scopes and admin mark, and its created and
last-changed times where the store gives them. Name the store the rows are in.

flags:
  -json
      print the secrets as JSON
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret show

usage: agent-secrets secret show NAME [--json] [--profile P]

Print an agent secret's name, store, secret name, owner, tier, kind, github-owners,
requesters, scopes, admin mark, shape, max grant, default grant, its created and
last-changed times, its deletion once it is deleted, with the earliest purge beside
it on Secrets Manager, and its versions; --json prints those and whether it has a value.
Never print its value.

flags:
  -json
      print the secret as JSON
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret create

usage: agent-secrets secret create NAME --owner me|shared|EMAIL --tier agent|human [--kind github-app|google-login|azure-login|google-service-account|none] [--github-owners LOGINS] [--requesters LIST] [--scopes LIST] [--admin true] [--shape token|document] [--max-grant DURATION] [--default-grant session] [--profile P]

Create an agent secret under the environment's cloud credential, then ask the broker to serve it.
--owner me is the email of the person that credential names, and is refused where it names
none; --owner EMAIL names the owning person by email. Read its value from standard input, or
type it at a prompt with echo off.

flags:
  -admin string
      true marks a secret whose grant is an administrator's: such a secret is human tier, so a person approves each release, names its requesters, and bounds its grants to an hour with --max-grant
  -default-grant string
      session: a request with no --ttl lasts until its session ends, not 12 hours
  -github-owners string
      the GitHub accounts a github-app secret mints for, separated by spaces ("<login> <login>")
  -kind string
      github-app, google-login, azure-login, google-service-account or none (the default)
  -max-grant string
      the longest grant duration this secret allows
  -owner string
      me (the email of the person your AWS or Google sign-in names), shared, or a person's email
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)
  -requesters string
      the people (each by their lowercase sign-in email) and registered services that may ask for this secret at all, separated by spaces ("<email> <service>"); an admin secret and a google-service-account one each need a --max-grant of an hour or less, and a secret that only lists who may ask keeps its own cap, or none
  -scopes string
      the OAuth scopes the token a google-service-account secret mints carries, each the part of a Google scope after https://www.googleapis.com/auth/, separated by spaces ("cloud-platform bigquery"); read on that kind alone, and a secret without it mints cloud-platform
  -shape string
      token: the value is one line, so the broker removes its trailing line endings before it spends it; document: every byte of the value is part of it, so the broker releases it unchanged. Unset, the broker removes a trailing line ending only from a value that holds none inside it
  -tier string
      agent (its owner's agents use it without asking) or human (a person approves each use)

agent-secrets secret set

usage: agent-secrets secret set NAME [--profile P]

Set a new agent-secret value under the environment's cloud credential. Then ask the broker to
serve it. Read the value from standard input, or type it at a prompt with echo off.

flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret retag

usage: agent-secrets secret retag NAME [--owner me|shared|EMAIL] [--tier agent|human] [--kind github-app|google-login|azure-login|google-service-account|none] [--github-owners LOGINS|none] [--requesters LIST|none] [--scopes LIST|none] [--admin true|none] [--shape token|document|none] [--max-grant DURATION|none] [--default-grant session|none] [--profile P]

Change an agent secret's owner, tier, kind, GitHub owners, requesters, scopes, admin mark,
shape, max grant or default grant under the environment's cloud credential. Then ask the broker
to reread it. none removes a kind, GitHub owners, requesters, scopes, the admin mark, a shape, a
max grant or a default grant, in a retag of its own. An administrator changes a shared secret's
owner and tier. This CLI cannot tell whether a requesters entry naming a service is one the
deployment registers: it holds no list of them, so the broker's answer to the reread is what
catches an unregistered name, printing its refusal and its reason, and the retag exits 1 with
the tag written.

flags:
  -admin string
      true marks a secret whose grant is an administrator's, or none removes the mark: such a secret is human tier, so a person approves each release, names its requesters, and bounds its grants to an hour with --max-grant
  -default-grant string
      session (no --ttl lasts until the session ends) or none (12 hours)
  -github-owners string
      the GitHub accounts a github-app secret mints for, separated by spaces ("<login> <login>"), or none
  -kind string
      github-app, google-login, azure-login, google-service-account or none
  -max-grant string
      the longest grant duration this secret allows, or none
  -owner string
      the new owner: me (the email of the person your AWS or Google sign-in names), shared, or a person's email
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)
  -requesters string
      the people (each by their lowercase sign-in email) and registered services that may ask for this secret at all, separated by spaces ("<email> <service>"), or none; an admin secret and a google-service-account one each need a --max-grant of an hour or less, and a secret that only lists who may ask keeps its own cap, or none
  -scopes string
      the OAuth scopes the token a google-service-account secret mints carries, each the part of a Google scope after https://www.googleapis.com/auth/, separated by spaces ("cloud-platform bigquery"), or none; read on that kind alone, and a secret without it mints cloud-platform
  -shape string
      token (the broker removes the value's trailing line endings before it spends it), document (the broker releases the value byte for byte) or none
  -tier string
      the new tier: agent or human

agent-secrets secret delete

usage: agent-secrets secret delete NAME [--profile P]

Schedule the agent secret NAME's deletion, restorable for 30 days, under the environment's
cloud credential, then ask the broker to stop serving it at once.

flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret restore

usage: agent-secrets secret restore NAME [--profile P]

Cancel the agent secret NAME's scheduled deletion under the environment's cloud credential,
then ask the broker to serve it again at once.

flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets NAME… – command

usage: agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] [--github-owner LOGIN [--github-repo NAME]... [--github-read-only]] [--github-token] -- <command> [args...]

Request secrets, wait up to --wait (default 30m) for a person to decide, and run <command>
with each granted secret in its environment under its NAME; nothing runs unless all are
granted. One line on stderr names those secrets and the broker and store they came from,
never a value. A name a person must approve needs --reason; with none the
whole request is denied. The grant lasts --ttl, or 15 minutes when any secret is human tier and 12 hours otherwise (until this session ends when every secret is tagged default-grant=session). --github-owner narrows each
GitHub App token the grant releases to that account's installation, and --github-repo and
--github-read-only narrow it further, to those repositories and to read access; a token
narrowed to repositories alone keeps every permission the App holds, so a machine that must
only read needs --github-read-only too. <command> runs only once the broker answers that it
applied the narrowing. Each GitHub App secret's NAME holds the JSON object of installations
the release makes; with --github-token it holds that one installation's token alone, which is
the form a command that sends the token to GitHub needs. --github-token needs --github-owner,
and nothing runs when a release holds other than one installation, or when the grant releases
no GitHub App token at all.

flags:
  -github-owner string
      narrow each GitHub App token the grant releases to this account's installation
  -github-read-only
      narrow the GitHub App token further, to contents: read, metadata: read, pull_requests: read and actions: read
  -github-repo value
      narrow the GitHub App token further, to this repository of --github-owner's (repeatable); it keeps the App's permissions unless --github-read-only is given too
  -github-token
      hand over each GitHub App token alone, in place of the JSON object of installations the release carries: the form a command that sends the token to GitHub needs, and it needs --github-owner
  -reason string
      why these secrets are needed; necessary where a person approves
  -ttl duration
      how long the grant lasts, a whole number of seconds such as 2m or 90s; unset, it lasts 15 minutes when any secret is human tier and 12 hours otherwise, or until this session ends when every secret is tagged default-grant=session
  -wait duration
      how long to wait for a pending request (default 30m0s)

agent-secrets-helper

usage:
  agent-secrets-helper [serve]     run the helper: listen on its socket, sign for the machine sessions
                                   registered with it, and enroll each with the broker
  agent-secrets-helper sessions    list live sessions: pid, runtime id, enrollment id, state
  agent-secrets-helper install [--url URL] [--restart-with-sessions]
                                   write this binary's systemd user unit, daemon-reload and
                                   enable it; restart a running helper only if it has no
                                   sessions, or --restart-with-sessions is given
  agent-secrets-helper --version   print the release this binary was built as

environment:
  AGENT_SECRETS_URL            the broker's base URL; serve needs it, install writes it into the unit
  AGENT_SECRETS_HELPER_SOCK    the helper's socket; install writes it into the unit when set
                               (default $XDG_RUNTIME_DIR/agent-secrets/helper.sock)
  AGENT_SECRETS_OPERATOR_FILE  a file holding the operator's Dispatch login, which a machine login
                               names as its approver; install writes it into the unit when set
                               (default ~/.config/agent-secrets/operator)
  AGENT_SECRETS_MACHINE_FILE   where the helper keeps this machine's login (its key and refresh
                               token, mode 0600), so a restart resumes it; install writes it into
                               the unit when set (default ~/.config/agent-secrets/machine.json).
                               A machine that proves an identity of its own keeps no such file;
                               it keeps the key it trades with in
                               ~/.config/agent-secrets/identity-key.pem, mode 0600
  AGENT_SECRETS_STATE_FILE     where the helper keeps its session records (mode 0600: a named
                               session's signing key is in them, so they must outlive a reboot
                               and sit beside this helper's own machine login, not in the
                               runtime directory and not at a path a second helper shares);
                               records found beside this helper's socket, where they used to
                               live, are moved here once (default: sessions.json beside
                               AGENT_SECRETS_MACHINE_FILE, so ~/.config/agent-secrets/sessions.json)
  AGENT_SECRETS_MACHINE_IDENTITY
                               the identity this machine proves at the broker's token exchange:
                               kubernetes (AGENT_SECRETS_MACHINE_TOKEN_FILE), metadata
                               (AGENT_SECRETS_MACHINE_AUDIENCE) or pool (both, with
                               AGENT_SECRETS_POOL_AUDIENCE and AGENT_SECRETS_POOL_ACCOUNT).
                               With it the helper's launcher credential is the one that exchange
                               mints, traded again before it lapses with the key it kept, and no
                               person approves this machine; unset, a person logs it in as before
  AGENT_SECRETS_KEY_DIR        where this user's session identity lives; install writes it into
                               the unit when set (default $XDG_RUNTIME_DIR/agent-secrets)
  AGENT_SECRETS_SIGNIN_DIR     where agent-secrets login keeps this user's sign-ins, which the
                               helper reads to decide whose authority each session enrols under,
                               and reads no other user's; install writes it into the unit when
                               set (default $XDG_STATE_HOME/agent-secrets/signins, which a
                               reboot keeps, where the key dir above does not)
  AGENT_SECRETS_SIGNIN_CLIENT_ID, AGENT_SECRETS_SIGNIN_CLIENT_SECRET_FILE, AGENT_SECRETS_SIGNIN_ISSUER
                               the device-flow client a person signed in with, which mints their
                               next identity token; without it a sign-in on this box cannot be
                               traded and every session enrols under this machine's credential
  AGENT_SECRETS_PERSON         which of this user's sign-ins a session enrols under, where more
                               than one person has signed in here
  AGENT_SECRETS_SESSION        the session name a trade writes under, where the deployment's
                               entry fixes none

install refuses a relative path in any of these variables: the unit's helper runs elsewhere.