Use tokens with package tools

Ravenstash uses two different kinds of token for command-line work:

Token	Where to use it
Automation token	Set it as RVS_TOKEN when running rvs.
Short-lived registry token	Give it directly to a package tool such as Gradle, Yarn, or Bun.

An automation token is not always accepted as a registry password. This can be disabled by your account or organization policy. In that case, keep the automation token in RVS_TOKEN and use rvs to create a short-lived token for the registry.

Use an automation token with rvs

Create an automation token in Ravenstash, save it in an approved secret manager, and expose it to the current command or job as RVS_TOKEN:

export RVS_TOKEN="${TOKEN_FROM_SECRET_STORE}"
rvs auth whoami

When RVS_TOKEN is present, rvs uses it instead of a browser sign-in saved on the computer. An invalid or empty value causes the command to fail; rvs does not silently fall back to another sign-in.

You can then use the normal Ravenstash commands:

rvs account switch AcmeHQ
rvs art select platform/packages
rvs pip install internal-sdk

For a developer computer, rvs auth login is usually more convenient than an automation token. See Automation tokens for guidance on ownership, permissions, rotation, and revocation.

Generate a short-lived token

Use this method when a package tool must connect to Ravenstash directly instead of running through rvs. Common examples include Gradle, sbt, Yarn, Bun, and tools for which an rvs wrapper cannot be used.

First, make sure rvs can sign in. Either run rvs auth login, or set the automation token supplied by Ravenstash as RVS_TOKEN. Then run:

rvs art token mint --target platform/packages --format pypi

The selected repository is used when --target is omitted. Choose --format when more than one format is enabled. The command prints one short-lived registry token. Use that value in the package tool’s password or token field, together with the repository address shown by Ravenstash. For tools that also require a username, use __token__.

Do not set the generated short-lived token as RVS_TOKEN. RVS_TOKEN remains the browser-independent automation token that authorizes rvs; the generated token is only for direct access to the chosen registry.

Optional flags

Flag	Default	When to use it
--format pypi|npm|maven|oci	Determined from the target	Add it when a repository supports more than one package format, or when Ravenstash asks you to choose.
--access read|publish|admin	read	Choose publish for uploads. Choose admin only when the package tool must delete content and the automation token permits it.
--duration 15m..12h	4h	Request a shorter or longer lifetime. The automation token’s expiry may shorten it.
--account NAME	Selected account	Use another Ravenstash username or organization public handle for this command.
--profile NAME	Selected profile	Use another local profile for this command.
Root rvs --json ...	Plain token	Include details such as the expiry time in JSON output. The JSON still contains the secret.

For example, create a publish token that lasts 30 minutes:

rvs art token mint \
  --target platform/packages \
  --format npm \
  --access publish \
  --duration 30m

--format is unnecessary when the chosen repository supports only one package format. A private mirror also identifies its package format automatically and supports read access only.

Use the short-lived token safely

• Copy the repository address from Ravenstash instead of constructing it.
• Keep the token out of source files, shell history, logs, images, and build output.
• Prefer an in-memory or temporary package-tool setting when one is available.
• Create a new token when the old one expires instead of saving it permanently.
• Give it only the access needed for the task.

The short-lived token cannot exceed the accounts, repositories, and actions allowed by the browser sign-in or automation token used to create it. Rotating or revoking the automation token also ends the authority used to create new registry tokens.

Print native setup instructions

Use rvs art endpoint to print the current read and publish addresses for one repository format:

rvs art endpoint --target platform/packages --format pypi

Add --access read or --access publish when a script needs one unlabelled address. The command discovers addresses; it does not create configuration or a credential.

Run rvs art native config TOOL for tool-specific setup templates before minting. It only prints instructions. The templates show credential references supported by each tool and identify any login commands that save credentials when executed.

The install and publication guides for PyPI, npm, Maven, Container, and Helm OCI include complete native-client examples.

For ORAS, a repository with OCI enabled gets Container and Helm instructions and one --format oci mint command. A native registry login has one credential entry per host: logging out of a shared Docker/ORAS/Helm store can affect another tool. The printed examples use separate temporary config files. Tokens for different repositories on the same host still require switching credentials.