Vuer Hub CLI

Environment management plugin for the Vuer CLI. Provides commands for managing simulation environments through the Vuer Hub registry.

Installation

pip install vuer-hub==0.3.0

Or with uv:

uv add vuer-hub==0.3.0

Requirements

• Python >= 3.10
• Vuer CLI (vuer>=0.1.6) — vuer-hub ships no command of its own; it registers subcommands that the vuer CLI discovers and runs.

Quick Start

# 1. Point the CLI at the hub and authenticate
export VUER_HUB_URL=https://api.vuer.ai
vuer login --env production

# 2. Publish an environment directory (must contain environment.json)
vuer envs-publish --directory ./my-environment

# 3. Download it back anywhere
vuer envs-pull my-environment/1.0.0 --output ./downloads

Commands

Once installed, the following commands become available through the vuer CLI:

Authentication

# Login to Vuer Hub (dev environment)
vuer login

# Login to production environment
vuer login --env production

Uses the OAuth Device Flow: the command prints a URL and a code, you authorize in the browser, and credentials are saved to ~/.vuer/credentials.

Environment Management

# Sync all dependencies from environment.json into vuer_environments/
vuer sync

# Add an environment to environment.json and sync
vuer add some-environment/1.2.3

# Remove an environment from environment.json and sync
vuer remove some-environment/1.2.3

# Upgrade an environment to the latest version
vuer upgrade some-environment

sync resolves transitive dependencies via the backend, downloads each environment into vuer_environments/<name>/<version>/, and writes an environments-lock.yaml with the resolved set. Re-running skips already-synced environments.

Browsing Versions

# List every published version of an environment, newest first
vuer envs-versions some-environment

[INFO] Found 3 versions for 'some-environment':
  1.2.5  2026-03-01 10:22
  1.2.4  2026-02-11 08:05
  1.0.0  2026-01-05 14:40

Useful for picking a version to pass to vuer add or vuer envs-pull, and for seeing what vuer upgrade would resolve to. Reading versions is a public operation, so this command works without vuer login; it only needs VUER_HUB_URL.

Publishing & Pulling

# Publish current directory as an environment
vuer envs-publish

# Publish from a specific directory
vuer envs-publish --directory ./my-environment

# Publish under an organization (environment becomes org-owned)
vuer envs-publish --org acme

# Simulate a publish without uploading (recommended first run)
vuer envs-publish --directory ./my-environment --dry-run

# Pull an environment from the registry (positional name/version)
vuer envs-pull my-environment/1.0.0

# Pull to a custom output directory
vuer envs-pull my-environment/2.0.0 --output ./downloads

envs-publish archives the directory into a .tgz (excluding __pycache__, .cache, .git and *.pyc) and uploads it. envs-pull streams the archive with a progress bar and extracts it to <output>/<name>/<version>/.

Public environments can be pulled, synced and listed without logging in. Anything else -- PRIVATE or ORG_MEMBERS -- requires vuer login, and reads as though it does not exist if you cannot see it.

Note: the same name + version cannot be published twice (the registry returns a conflict). Bump the version in environment.json to publish an update.

Ownership and visibility

Two independent choices. --org (or organization in environment.json) sets who owns the environment; visibility sets who can see it. Without an org, it is owned by you personally.

To publish something your team can use but outsiders cannot:

{
  "name": "acme-robot",
  "version": "1.0.0",
  "visibility": "ORG_MEMBERS",
  "organization": "acme"
}

vuer envs-publish          # or: vuer envs-publish --org acme

You have to be a member of the org, otherwise the publish is rejected. --org overrides organization from the file, warns when the two differ, and never rewrites the file.

The environment.json file

envs-publish, sync, add and remove all operate on an environment.json in the target directory. Minimum required fields are name and version:

{
  "name": "my-environment",
  "version": "1.0.0",
  "description": "Short description of the environment",
  "visibility": "PUBLIC",
  "organization": "acme",
  "env-type": "genesis",
  "dependencies": {
    "some-dependency": "1.2.3"
  }
}

• name — required, no whitespace.
• version — required, valid semver (e.g. 1.0.0).
• visibility — PUBLIC, PRIVATE, or ORG_MEMBERS (default PUBLIC).
• organization — org slug to publish under; omit to own it yourself. See Ownership and visibility.
• env-type — free-form environment type tag (e.g. genesis, isaac).
• dependencies — map of name → exact version for transitive resolution. Ranges (^1.2.3, ~1.2.3) are not supported; vuer envs-versions <name> lists what you can pin to.

Environment Variables

• VUER_HUB_URL - Base URL of the Vuer Hub API (e.g. https://api.vuer.ai)
• VUER_AUTH_TOKEN - JWT token, used instead of your vuer login credentials. A stale value here silently shadows a fresh login, so unset it if you get "invalid or expired token" right after logging in.
• VUER_CLI_DRY_RUN - Set to any value (except "0", "false", "False") to enable dry-run mode

Configuration

Credentials are stored in ~/.vuer/credentials after running vuer login.

License

MIT