rvs command reference

This reference covers the public rvs command surface. Run rvs COMMAND --help for every option supported by your installed patch release.

rvs art and rvs artifacts are equivalent. Repository commands live under rvs art repo; there is no top-level rvs repo command.

Global options

Option	Purpose
`--version`, `-V`	Print the installed version.
`--json`	Emit `rvs`-owned output as JSON. Delegated native tools keep their own format.
`--install-completion`	Install completion for the current shell.
`--show-completion`	Print completion code for manual installation or customization.

Authentication

Command	Purpose
`rvs auth login`	Start browser-backed device login.
`rvs auth logout`	Remove credentials for a local profile while retaining its non-secret metadata.
`rvs auth logout --all`	Remove credentials from every local profile.
`rvs auth status`	Show whether a local credential is available.
`rvs auth whoami`	Verify and show the authenticated Ravenstash user.
`rvs artifacts auth print-token --target namespace/repository --kind pypi --access read --duration 4h`	Generate a temporary native credential; 15 minutes to 12 hours, default four hours. `--json` includes expiry metadata.

Common authentication options are --profile, --duration, and --no-browser. Use --api-url only with an endpoint Ravenstash has explicitly provided.

Local profiles

Command	Purpose
`rvs profile list`	List configured local CLI profiles.
`rvs profile current`	Show the effective profile, its selection source, endpoints, and credential-store choice.
`rvs profile current --verbose`	Show every resolved package repository endpoint.
`rvs profile use PROFILE`	Use a profile in this shell or as the persisted default.
`rvs profile rename OLD NEW`	Rename a profile and require fresh login for the new credential key.
`rvs profile delete PROFILE`	Delete its metadata and stored credentials.
`rvs profile delete --all`	Delete every local profile and its credentials.

A local profile is named CLI configuration and a credential slot. It is not the authenticated user or the acting customer account.

Accounts

Command	Purpose
`rvs account list`	List personal and organization accounts available to a local profile’s user.
`rvs account current`	Show the account used for authorization and usage attribution.
`rvs account use ACCOUNT`	Use `personal`, `org:LABEL`, or a stable account reference in this shell or local profile.
`rvs context current`	Verify the user and show the effective profile, account, target, and selection provenance.

Use --profile on these commands to inspect or change another local profile. Using an acting account does not change the authenticated user.

Shell context

rvs shell setup [--shell bash|zsh|fish]

This installs the session-aware prompt hook. It displays the effective local profile, acting account, and package target and keeps later selections local to that shell. It is separate from rvs runtime setup-shell, which installs runtime shims.

Package context

Command	Purpose
`rvs art select TARGET`	Save a private repository or mirror target for the effective profile and acting account.
`rvs art current`	Show the current profile, account, and target.
`rvs art clear`	Clear the selected target without changing login or account.
`rvs art --target TARGET install PACKAGE...`	Install once from an explicit target.

Target syntax:

Type	Syntax	Access
Internal repository	`namespace/repository` or `internal:namespace/repository`	Read and publish according to registry kind
Global repository	`global:namespace/repository`	Reserved syntax; currently unavailable
Official mirror	`mirror:source`	Read only
Custom mirror	`custom-mirror:name`	Read only

Bare repository selectors currently resolve in the internal realm. Immutable selectors use internal:in_XXXXXXXX/r_XXXXXXXX; future global selectors use global:gn_XXXXXXXX/r_XXXXXXXX. Ravenstash rejects ambiguous matches rather than choosing one silently.

Package-group options must appear before the subcommand:

rvs art \
  [--profile PROFILE] \
  [--account ACCOUNT] \
  [--target TARGET] \
  [--kind KIND] \
  install PACKAGE...

Use --kind only when target or package syntax does not determine one registry kind.

Private repositories

Command	Purpose
`rvs art repo list`	List repositories across available accounts, optionally filtered with `--registry-kind`.
`rvs art repo create NAME --registry-kind KIND`	Create a repository; repeat the option to enable several kinds.
`rvs art repo show REPOSITORY`	Show details and enabled registry kinds.
`rvs art repo rename REPOSITORY NEW_NAME`	Rename the logical repository and its routes.
`rvs art repo delete REPOSITORY`	Delete after confirmation.
`rvs art repo upstream list REPOSITORY KIND`	List the ordered upstream plan for one registry kind in a repository.
`rvs art repo upstream add REPOSITORY KIND --remote-cache CACHE_ID`	Attach a private mirror’s backing remote cache.
`rvs art repo upstream add REPOSITORY KIND --private-repository NAMESPACE/REPOSITORY`	Attach the matching registry kind from another private repository in the same account.
`rvs art repo upstream remove REPOSITORY KIND ATTACHMENT_ID`	Remove one upstream attachment.

Registry kinds are pypi, npm, maven, container, and helm. Use rvs art select to choose the active repository.

Private mirrors

Use rvs art mirror to manage private mirrors.

Command	Purpose
`rvs art mirror list`	List official and custom mirrors for the selected account.
`rvs art mirror add SOURCE`	Add a curated official mirror.
`rvs art mirror create-custom NAME`	Create a custom mirror backed by an HTTPS package source.
`rvs art mirror show CACHE_ID`	Show one mirror and its backing remote-cache identity.
`rvs art mirror set-age CACHE_ID --min-age-hours HOURS`	Change the minimum upstream package age for direct mirror use.
`rvs art mirror delete CACHE_ID`	Delete after confirmation when it is no longer connected.
`rvs art mirror select SOURCE`	Select an official mirror.
`rvs art mirror select --custom NAME`	Select a custom mirror.
`rvs art mirror current`	Show the current package context.
`rvs art mirror clear`	Clear the selected package target.

Official mirror creation options include --select, --kind, and age controls. Custom mirror creation requires --kind, --api-url, and --publication-control user-controlled|externally-controlled; it also supports --artifact-url, --auth-scheme none|basic|bearer, --username, --secret-env, repeatable --allowed-host, age controls, storage selection, and --select.

Never put an upstream secret directly in the command. --secret-env names the environment variable containing it.

Packages and versions

These commands require --repo and --registry-kind pypi|npm|maven:

Command	Purpose
`rvs art package list`	List packages in one repository and registry type.
`rvs art package show NAME`	Show versions, files, and usage.
`rvs art package yank NAME VERSION`	Yank a supported version, optionally with `--reason`.
`rvs art package delete-version NAME VERSION`	Delete one version after confirmation.
`rvs art package delete NAME`	Delete a package and all versions after confirmation.

Package helpers

Group	Commands
`rvs art pypi`	`index-url`, `upload-url`, `install`, `publish`, `configure`
`rvs art npm`	`registry-url`, `npmrc`, `install`, `publish`, `configure`
`rvs art maven`	`repo-url`, `settings`, `install`, `deploy`, `configure`

Helpers use the selected target or package-group --target. Publish helpers reject mirror targets.

Examples:

rvs art pypi install internal-sdk==1.2.3
rvs art pypi publish dist/

rvs art npm install @acme/design-system
rvs art npm publish .

rvs art maven install com.acme:internal-sdk:1.2.3
rvs art maven deploy target/internal-sdk-1.2.3.jar \
  --group com.acme --artifact internal-sdk --version 1.2.3

Native package-tool wrappers

rvs pip, rvs uv, rvs twine, rvs npm, and rvs mvn accept:

Option	Purpose
`--rvs-profile PROFILE`	Select a local profile once.
`--rvs-account ACCOUNT`	Select the personal or organization account once.
`--rvs-target TARGET`	Select a private repository or compatible mirror once.
`--rvs-native-config POLICY`	Use `respect`, `override`, or `isolate`; default is `respect`.

Select a repository or mirror before running the wrapper. Advanced wrapper options remain available for scripts that require an invocation-specific profile, account, or configuration policy.

rvs art select platform/packages
rvs pip install internal-sdk
rvs npm ci
rvs uv --rvs-native-config isolate sync

OCI wrappers

Command	Purpose
`rvs docker`	Run Docker with a temporary Container credential; push, pull, and tag accept short image names.
`rvs helm`	Run Helm with a temporary Helm OCI credential and selected-repository chart paths.
`rvs oras –rvs-kind container	helm`
`rvs oci-reference –kind container	helm`

These commands accept the corresponding profile, account, and target options. OCI operations require a private repository; private mirrors are not supported.

Docker examples after rvs art select namespace/repository:

rvs docker push team/api:1.0.0
rvs docker pull team/api:1.0.0
rvs docker tag local-api:dev team/api:next

The docker image push, image pull, and image tag forms behave identically. Use --rvs-target namespace/repository for one invocation without changing the saved selection. Docker global options such as --context and --config precede the Docker subcommand. Shorthand does not apply to build output tags or Dockerfiles.

Helm examples after rvs art select namespace/repository:

rvs helm push api-1.2.3.tgz
rvs helm push api-1.2.3.tgz team/backend
rvs helm pull team/backend/api --version 1.2.3
rvs helm install my-release team/backend/api --version 1.2.3
rvs helm show values team/backend/api --version 1.2.3

Shorthand covers push, pull, install, upgrade, show, and template. Full oci:// references remain accepted. Local paths must be explicit (./api); packaged .tgz charts stay local. --repo preserves Helm’s explicit repository selection. Dependency URLs in Chart.yaml are unchanged. See Helm reference rules.

Runtime management

Command	Purpose
`rvs runtime install RUNTIME VERSION`	Install Python, Node.js, or Java beneath `~/.rvs/runtimes`.
`rvs runtime uninstall RUNTIME VERSION`	Remove a managed runtime.
`rvs runtime list`	List managed runtimes.
`rvs runtime which RUNTIME [VERSION]`	Print an installed runtime’s executable path.
`rvs runtime use RUNTIME VERSION`	Pin a version in the current project.
`rvs runtime env`	Print shell initialization for runtime shims.
`rvs runtime setup-shell`	Update a Bash, Zsh, or Fish startup file with runtime shims.
`rvs runtime doctor`	Diagnose local runtime-manager state.

CLI updates

Command	Purpose
`rvs update`	Check the signed APT repository for an update.
`rvs update --apply`	Install the available signed update.