Metadata-Version: 2.5
Name: vuer-hub
Version: 0.3.0
Summary: Vuer Hub CLI - environment management plugin for vuer CLI
Project-URL: Homepage, https://github.com/fortyfive-labs/vuer-hub
Project-URL: Repository, https://github.com/fortyfive-labs/vuer-hub
Project-URL: Documentation, https://vuer-hub.readthedocs.io
Project-URL: Issues, https://github.com/fortyfive-labs/vuer-hub/issues
Project-URL: Changelog, https://github.com/fortyfive-labs/vuer-hub/blob/main/docs/CHANGE_LOG.md
Author-email: Ge Yang <ge.ike.yang@gmail.com>
License-Expression: MIT
Keywords: cli,robotics,simulation,vuer,vuer-hub
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: params-proto>=3.2.0
Requires-Dist: requests>=2.25.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: vuer>=0.1.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.0; extra == 'docs'
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-autobuild>=2024.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.5; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Requires-Dist: sphinxcontrib-video>=0.2; extra == 'docs'
Description-Content-Type: text/markdown

# Vuer Hub CLI

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

## Installation

```bash
pip install vuer-hub==0.3.0
```

Or with uv:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

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

```text
[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

```bash
# 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:

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

```bash
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`:

```json
{
  "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](https://semver.org) (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](#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
