Secrets CLI

Use outray secrets --help to see commands. Secrets authentication checks OUTRAY_TOKEN, then OUTRAY_API_KEY, then credentials from outray login. Prefer OUTRAY_TOKEN for machine credentials.

Select a target

outray secrets use --org my-team --vault orders-api --env development

The command can interactively offer accessible organizations, vaults, and environments. In automation, provide explicit selections. It writes [secrets] target metadata in the nearest outray/config.toml (or the file chosen with --config):

[secrets]
org = "my-team"
vault = "orders-api"
environment = "development"

Explicit --org, --vault, and --env options override environment-variable and file defaults. Supported defaults include OUTRAY_ORG, OUTRAY_SECRETS_VAULT, and OUTRAY_SECRETS_ENVIRONMENT. Organization selection also falls back to the authenticated active organization. Legacy --project and OUTRAY_SECRETS_PROJECT remain accepted; use vault terminology in new configuration.

List, set, and import

outray secrets list
outray secrets set DATABASE_URL
outray secrets import --from .env.local

list is metadata-only. Add --values only when you intend to reveal dotenv-formatted plaintext on stdout. set reads a hidden terminal prompt; it does not accept a value as a positional argument, keeping values out of command history and process arguments.

For automation, pipe a trusted secret source into outray secrets set DATABASE_URL --value-stdin. The CLI removes one trailing line break from stdin. Import can also use --from - for stdin. Do not print real values into shell history to construct a pipeline.

Inject values into a process

outray secrets run -- npm run dev
outray secrets run --watch -- npm run dev

The -- separates CLI flags from the child command. Values override matching inherited variables, but the parent shell is not changed. OUTRAY_TOKEN and OUTRAY_API_KEY are removed from the child even if a secret uses one of those names.

--watch polls the environment revision every five seconds by default and restarts the child after changes. Set --watch-interval 10 for a ten-second polling interval (minimum one second). Removed managed keys are removed from the restarted child's environment. This is process restart behavior, not in-place hot mutation of a running application's configuration.

Temporary connection failures can leave the child running with its last values and produce a warning after repeated failures. Invalid credentials, denied access, or an unavailable target are terminal watch errors. Review the terminal rather than assume the process has the newest values.

Export only when necessary

outray secrets pull --out .env.local
outray secrets pull --format json --out secrets.local.json

Without --out, plaintext is written to stdout. File export refuses to overwrite an existing file by default; --force permits replacement. Keep exported files out of version control, protect their access, and remove them when no longer needed. Runtime injection usually avoids needing a local file.

Delete and restore a version

outray secrets delete DATABASE_URL
outray secrets rollback DATABASE_URL --version 2

Both ask for confirmation in a terminal. --yes permits non-interactive execution. Delete moves the value into Trash; rollback restores a historical value as described in history.

Production and conflicts

Use --confirm-production for protected value access or mutations, including list --values, pull, set, import, delete, rollback, and run. Metadata-only listing does not need it. A token scope and production confirmation are separate checks.

Mutations use environment revisions and expected secret versions to detect concurrent changes. If a conflict occurs, read the latest metadata and review the new value before retrying. Do not force an overwrite simply to make a concurrent-change warning disappear.