Metadata-Version: 2.4
Name: vuer-hub
Version: 0.1.0
Summary: Vuer Hub CLI - environment management plugin for vuer CLI
Project-URL: Repository, https://github.com/fortyfive-labs/vuer-hub
License-Expression: MIT
Keywords: cli,robotics,simulation,vuer,vuer-hub
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.0
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
```

Or with uv:

```bash
uv add vuer-hub
```

## Requirements

- Python >= 3.10
- Vuer CLI (`vuer>=0.1.0`)

## 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.

### Publishing & Pulling

```bash
# Publish current directory as an environment
vuer envs-publish

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

# 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>/`.

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

## 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",
  "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`).
- `env-type` — free-form environment type tag (e.g. `genesis`, `isaac`).
- `dependencies` — map of `name` → `version` for transitive resolution.

## Environment Variables

- `VUER_HUB_URL` - Base URL of the Vuer Hub API (e.g. `https://api.vuer.ai`)
- `VUER_AUTH_TOKEN` - JWT token for authentication (alternative to `vuer login`)
- `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
