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.

visibility	Who can see it	Needs an org
PUBLIC	Anyone, without logging in	No
PRIVATE	Only you, even when org-owned	No
ORG_MEMBERS	Every member of the owning org	Yes

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