Metadata-Version: 2.5
Name: eastworlds-forge
Version: 0.2.0
Summary: The Forge command-line interface: sign in with a Forge API key, download and upload dataset episodes, convert MCAP <-> LeRobot v2.1 locally.
Project-URL: Documentation, https://forge.eastworlds.io/how-to/cli
Project-URL: Source, https://github.com/Eastworld-Labs/forge_cli
Project-URL: Releases, https://github.com/Eastworld-Labs/forge_cli/releases
Requires-Python: >=3.10
Requires-Dist: av>=15
Requires-Dist: httpx>=0.27
Requires-Dist: mcap-ros2-support>=0.5
Requires-Dist: mcap>=1.2
Requires-Dist: numpy>=1.26
Requires-Dist: platformdirs>=4
Requires-Dist: pyarrow>=15
Requires-Dist: rich>=13
Requires-Dist: tomli-w>=1
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: keyring
Requires-Dist: keyring>=25; extra == 'keyring'
Description-Content-Type: text/markdown

# forge

The Forge command-line interface. Sign in once with a Forge API key, then download and upload dataset episodes, convert MCAP ↔ LeRobot v2.1, and lower the video frame rate. **Conversion and frame-rate changes run on your computer only**; Forge stores and serves episodes exactly as they were uploaded.

The full guide is on Forge: **[Documentation → Command-Line Interface (CLI)](https://forge.eastworlds.io/how-to/cli)**.

## Install

**Linux only:** x86_64 or arm64, glibc 2.28+ (e.g. Ubuntu 20.04+, Debian 12+, RHEL/Rocky 8+). On Windows, run it inside WSL2 (Ubuntu). macOS is not supported. No root, Python or ffmpeg needed.

```bash
curl -fsSL https://forge.eastworlds.io/install.sh | bash
```

This installs forge with its own Python into `~/.forge` (about 310 MB) and links `forge` and `eforge` (the same program) into `~/.local/bin`. A specific version: `… | bash -s -- 0.2.0`.

Prefer a Python tool manager (Linux)? `uv tool install eastworlds-forge` or `pipx install eastworlds-forge`.

## Sign in

```bash
forge
```

The first run opens **Forge → API keys** with a CLI key filled in. Press **Create**, copy the command the page shows, and paste it at the prompt. In CI, set `FORGE_API_KEY` instead.

## Use

```bash
forge datasets list
forge download eastworlds/yam-fold-handkerchief -o ./data --verdict valid
forge download eastworlds/yam-fold-handkerchief -o ./lerobot --format lerobot-v21 --fps 10
forge upload ./recordings/2026-09-29 --to eastworlds/yam-fold-handkerchief
forge convert mcap-to-lerobot ./data/eastworlds/yam-fold-handkerchief -o ./lerobot/yam_fold
forge convert lerobot-to-mcap ./lerobot/yam_fold -o ./mcap_again
```

Global options such as `--json`, `--profile` and `-y` go before the command: `forge --json datasets list`.

`forge update` updates, `forge doctor` checks the setup, `forge uninstall` removes everything (your keys stay unless you confirm).

| Exit code | Meaning |
|---|---|
| 0 | OK |
| 1 | Failure |
| 2 | Usage or validation error |
| 3 | Bad or expired key |
| 4 | Missing scope |
| 5 | Not found |
| 6 | Conflict |
| 7 | Server or network error |
| 130 | Interrupted |

## Develop

```bash
python3.11 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check src tests
```

- `src/forge_cli/convert/` is a port of the production-verified MCAP → LeRobot v2.1 converter. `tests/test_convert_golden.py` compares the two on real recordings when `FORGE_VERIFIED_SAMPLE` and `FORGE_GOLDEN_EPISODES` are set.
- `install/install.sh` is the installer; `tests/test_install.py` runs it against a local fake release.
- `scripts/build_release.py --out dist/release` builds what the download host serves. On a `vX.Y.Z` tag, `.github/workflows/release.yml` publishes it to Tencent COS behind EdgeOne (`https://cli-forge.eastworlds.io`); setup in [docs/RELEASE_INFRA.md](docs/RELEASE_INFRA.md).

Design: [docs/INITIAL_PLAN_V2.md](docs/INITIAL_PLAN_V2.md). What was built: [docs/INITIAL_DONE_V2.md](docs/INITIAL_DONE_V2.md).
