Metadata-Version: 2.4
Name: vuer-cli
Version: 0.0.5
Summary: A Python CLI for Vuer, a real-time 3D visualization library
Project-URL: Homepage, https://github.com/vuer-ai/vuer-cli
Project-URL: Repository, https://github.com/vuer-ai/vuer-cli
Project-URL: Issues, https://github.com/vuer-ai/vuer-cli/issues
Author-email: Ge Yang <ge.ike.yang@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: params-proto>=3.2.3
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: all
Requires-Dist: mcap-ros2-support>=0.5.0; extra == 'all'
Requires-Dist: mcap>=1.1.0; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: opencv-python>=4.8.0; extra == 'all'
Requires-Dist: pandas>=2.0.0; extra == 'all'
Requires-Dist: vuer>=0.0.81; extra == 'all'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx>=4.0; extra == 'docs'
Requires-Dist: tomli>=1.1.0; (python_version < '3.11') and extra == 'docs'
Provides-Extra: example
Provides-Extra: mcap
Requires-Dist: mcap-ros2-support>=0.5.0; extra == 'mcap'
Requires-Dist: mcap>=1.1.0; extra == 'mcap'
Requires-Dist: numpy>=1.24.0; extra == 'mcap'
Requires-Dist: opencv-python>=4.8.0; extra == 'mcap'
Requires-Dist: pandas>=2.0.0; extra == 'mcap'
Provides-Extra: viz
Requires-Dist: numpy>=1.24.0; extra == 'viz'
Requires-Dist: opencv-python>=4.8.0; extra == 'viz'
Requires-Dist: pandas>=2.0.0; extra == 'viz'
Requires-Dist: vuer>=0.0.81; extra == 'viz'
Description-Content-Type: text/markdown

# Vuer Hub Environment Manager

Vuer HUB and the vuer command line tool enable you to manage, version-control,
and distribute physical simulation environments the same way you manage
software packages.

## Installation

```bash
pip install vuer-cli==0.0.4
```

or with uv:

```bash
uv add vuer-cli==0.0.4
```

## Environment Variables

| Variable          | Required | Description                                                              |
|-------------------|----------|--------------------------------------------------------------------------|
| `VUER_AUTH_TOKEN` | ✅        | JWT token used for all authenticated requests                            |
| `VUER_HUB_URL`    | ✅        | Base URL of the Vuer Hub API (required — no default; e.g. `https://hub.vuer.ai/api`) |

## Commands

| Command        | Description                                                           |
|----------------|-----------------------------------------------------------------------|
| `vuer`         | Show top-level help and list available commands                       |
| `vuer --help`  | Show detailed CLI help                                                 |
| `login`        | Authenticate with Vuer Hub using OAuth Device Flow                    |
| `sync`         | Sync all environments from environment.json dependencies (like npm install) |
| `add`          | Add an environment dependency to environment.json                     |
| `remove`       | Remove an environment dependency from environment.json                |
| `upgrade`      | Upgrade an environment dependency in environment.json to latest       |
| `envs-publish` | Publish an environment version                                        |
| `envs-pull`    | Download an environment by ID or `name/version`                       |

## Usage

### Authentication

The easiest way to authenticate is using the `login` command:

```bash
# Set the Hub URL first
export VUER_HUB_URL="https://hub.vuer.ai/api"

# Login with dev environment (default)
vuer login

# Or login with production environment
vuer login --env production
```

**After successful authentication:**
- ✅ Credentials are automatically saved and configured
- ✅ **Vuer CLI will automatically use the saved credentials** - no manual setup needed!
- ✅ Works immediately in the current terminal
- ✅ Works in all new terminals (auto-configured)
- ✅ Cross-platform support (Windows, macOS, Linux)

**How it works:**
1. Saves credentials to `~/.vuer/credentials` (used automatically by CLI)
2. Creates shell script at `~/.vuer/env.sh` (for manual use if needed)
3. **Windows**: Sets user environment variables via `setx`
4. **macOS/Linux**: Automatically adds to your shell config (~/.zshrc or ~/.bashrc)

**Manual setup (optional):**

If you prefer to set environment variables manually:

```bash
export VUER_HUB_URL="https://hub.vuer.ai/api"
export VUER_AUTH_TOKEN="eyJhbGci..."
# Optional: enable dry-run mode to simulate operations (no network changes)
export VUER_CLI_DRY_RUN="1"
```

### Basic Commands

```bash
# Sync all environments from environment.json dependencies
# Reads environment.json in current directory, validates dependencies,
# and downloads all environments (including transitive deps) to vuer_environments/
vuer sync
vuer sync --output ./my-envs

# Publish an environment (requires environment.json in the directory)
vuer envs-publish --directory ./my-environment

# Pull an environment (download and unpack into a directory)
vuer envs-pull <environmentId>
vuer envs-pull my-environment/1.0.0

# Add an environment
vuer add --env <environmentId>
```

### Sync Command Details

The `sync` command works like `npm install`:

1. Reads `environment.json` from the current directory
2. Parses the `dependencies` field (e.g., `{"some-dependency": "1.2.3"}`)
3. Validates all dependencies exist in the backend
4. Fetches transitive dependencies for each environment
5. Downloads all environments (direct + transitive) to `vuer_environments/` directory
6. Preserves `environment.json` inside downloaded environment directories

Publishing metadata (used by `envs-publish`)

```json
{
  "name": "my-environment",
  "version": "v1.0.0",
  "description": "Demo robotic arm env",
  "visibility": "PUBLIC",
  "env-type": "isaac",
  "dependencies": {
    "my-environment-1": "v4.0.0"
  }
}
```

Fields and recommendations for publishing metadata
- **name** (string, required): logical name of the environment (no slashes). This becomes the directory name under `vuer_environments/<name>/<version>/` when downloaded.
- **version** (string, required): environment version string. Use a stable, reproducible format (we recommend semantic style like `v1.0.0`).
- **description** (string, optional): short human-readable description of the environment.
- **visibility** (string, optional): publishing visibility, commonly `PUBLIC` or `PRIVATE`.
- **env-type** (string, optional): environment runtime/type identifier (for example `isaac`, `gazebo`, etc.).
- **dependencies** (object, optional): mapping of dependency-name → version (e.g. `"some-dependency": "v1.2.3"`). These declare upstream environment dependencies and are validated during publish.

Publishing notes
- `envs-publish` expects the target directory to contain a valid `environment.json`. At minimum `name` and `version` must be present; `envs-publish` will validate metadata before uploading to `VUER_HUB_URL`.
- The `environment.json` baked into an environment package is preserved when that package is later downloaded to `vuer_environments/<name>/<version>/`.
- Keep the publishing `environment.json` authoritative: use `dependencies` to declare exact `name → version` mappings for transitive resolution.

Project-level `environment.json` used by `vuer sync`

For projects that consume environments (i.e., run `vuer sync`), you usually keep a simple `environment.json` at the project root that focuses on the `dependencies` map:

```json
{
  "dependencies": {
    "some-dependency": "v1.2.3",
    "another-dependency": "v4.5.6"
  }
}
```

Note: The project-level `environment.json` used by `vuer sync` typically only needs a `dependencies` mapping. The publishing `environment.json` (shown above) must include `name` and `version`.

Use `vuer <command> --help` for full options.

### Add Command Details

- Purpose: add an environment dependency to the current directory's `environment.json`.
- Input: an environment identifier in canonical `name/version` form or a hub-specific environment ID (example: `my-environment/1.0.0`).
- Behavior: validates the environment exists on the configured `VUER_HUB_URL` and updates the `dependencies` section of `environment.json`. Run `vuer sync` afterwards to download the environment and its transitive dependencies into `vuer_environments/`.

### Remove Command Details

- Purpose: remove a specific environment dependency from the current directory's `environment.json`.
- Input: a canonical `name/version` spec (exact match required).
- Behavior: removes only the exact `name/version` entry from `environment.json`. If the corresponding version directory exists under `vuer_environments/<name>/<version>/`, the local copy will be removed; empty parent directories are cleaned up automatically.

### Upgrade Command Details

- Purpose: update an existing dependency in `environment.json` to a newer version.
- Input: a dependency name (to upgrade to the latest available) or an explicit `name/version` to target.
- Behavior: queries the configured hub for available versions, updates `environment.json` with the selected version, and leaves installation to `vuer sync`.

### envs-publish Command Details

- Purpose: publish a prepared environment directory to the configured hub.
- Input: a local directory containing an `environment.json` and environment content.
- Behavior: validates the local environment metadata, then uploads the environment as a new version to `VUER_HUB_URL`. Authenticated operations require `VUER_AUTH_TOKEN`.

### envs-pull Command Details

- Purpose: download an environment from the hub and place it into a local directory.
- Input: a hub environment ID or canonical `name/version` (e.g., `my-environment/1.0.0`).
- Behavior: downloads the environment and creates the nested path `vuer_environments/<name>/<version>/` (or an alternate `--output` path), preserving the bundled `environment.json` metadata.
