Implementation:Haosulab ManiSkill Download Demo CLI

Field	Value
Source Repository	haosulab/ManiSkill
Type	External Tool Doc
Domains	Imitation_Learning, Robotics, Data_Processing
Last Updated	2026-02-15

Overview

Description

The Download Demo CLI is a command-line utility provided by ManiSkill for downloading pre-collected expert demonstration datasets from the official HuggingFace repository. It handles the full download lifecycle: resolving the dataset URL for a given environment ID, downloading the ZIP archive with progress reporting, extracting the contained HDF5 (.h5) and JSON (.json) trajectory files, and cleaning up the archive. The tool supports downloading demonstrations for individual environments, all environments at once, or filtered by environment type (rigid_body or soft_body).

The downloaded files are placed in a configurable output directory (defaulting to ~/.maniskill/demos or the path set by the MS_ASSET_DIR environment variable). Each dataset consists of a trajectory.h5 file containing per-episode trajectory data (actions, environment states, reset kwargs) and a companion trajectory.json file with episode metadata.

Usage

This tool is invoked as the first step in the imitation learning pipeline, before trajectory replay/conversion and policy training. It is used when the practitioner needs expert demonstrations for a supported ManiSkill environment.

Code Reference

Source Location

Field	Value
Repository	haosulab/ManiSkill
File	mani_skill/utils/download_demo.py
Lines	L80-147 (argument parsing and main download logic)

Signature

CLI invocation:

python -m mani_skill.utils.download_demo <uid> [-o OUTPUT_DIR] [--quiet]

Argument parser (L80-102):

def parse_args(args=None):
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "uid",
        type=str,
        nargs="?",
        default="",
        help="An environment id (e.g. PickCube-v1) or 'all' for all available demonstrations.",
    )
    parser.add_argument("--quiet", action="store_true", help="Disable verbose output.")
    parser.add_argument(
        "-o",
        "--output_dir",
        type=str,
        help="The directory to save demonstrations to. The files will then be saved to "
             "<output_dir>/<env_type>/<env_id>. By default it is saved to ~/.maniskill/demos "
             "or what MS_ASSET_DIR is set to.",
    )
    return parser.parse_args(args)

Key parameters:

Parameter	Type	Default	Description
uid	str	"" (lists available)	Environment ID (e.g. PickCube-v1), "all", "rigid_body", or "soft_body"
-o / --output_dir	str	~/.maniskill/demos	Directory to save downloaded demonstrations
--quiet	flag	False	Suppress verbose output and progress bars

Import

This tool is designed to be run as a module from the command line:

python -m mani_skill.utils.download_demo PickCube-v1

For programmatic use:

from mani_skill.utils.download_demo import main, parse_args

# Download demos for PickCube-v1
main(parse_args(["PickCube-v1"]))

I/O Contract

Inputs:

Input	Type	Description
uid	str	Environment identifier string. Must be a key in DATASET_SOURCES (e.g. "PickCube-v1", "StackCube-v1"), "all", "rigid_body", or "soft_body". If empty, prints available UIDs.

Outputs:

Output	Type	Description
trajectory.h5	HDF5 file	Per-episode trajectory data containing actions, env_states, and metadata organized under traj_0, traj_1, etc.
trajectory.json	JSON file	Episode metadata including episodes (list of episode dicts with episode_id, episode_seed, reset_kwargs, control_mode, elapsed_steps) and env_info (env_id, env_kwargs).

Available environment UIDs (rigid_body):

• AnymalC-Reach-v1, DrawTriangle-v1, LiftPegUpright-v1, PegInsertionSide-v1
• PickCube-v1, PlugCharger-v1, PokeCube-v1, PullCube-v1, PullCubeTool-v1
• PushCube-v1, PushT-v1, RollBall-v1, StackCube-v1, StackPyramid-v1
• TwoRobotPickCube-v1, TwoRobotStackCube-v1

Data source URL pattern:

https://huggingface.co/datasets/haosulab/ManiSkill_Demonstrations/resolve/main/demos/{env_id}.zip?download=true

Usage Examples

Example 1: List available demonstrations

python -m mani_skill.utils.download_demo
# Output: Available dataset UIDs:
# ['AnymalC-Reach-v1', 'DrawTriangle-v1', 'LiftPegUpright-v1', ...]

Example 2: Download demonstrations for a single environment

python -m mani_skill.utils.download_demo PickCube-v1
# Downloads to ~/.maniskill/demos/PickCube-v1/

Example 3: Download to a custom directory

python -m mani_skill.utils.download_demo StackCube-v1 -o /data/maniskill_demos
# Downloads to /data/maniskill_demos/StackCube-v1/

Example 4: Download all available demonstrations quietly

python -m mani_skill.utils.download_demo all --quiet

Example 5: Programmatic download

from mani_skill.utils.download_demo import main, parse_args

# Download PegInsertionSide-v1 demos to a custom directory
args = parse_args(["PegInsertionSide-v1", "-o", "./my_demos"])
main(args)

Related Pages

• Principle:Haosulab_ManiSkill_Demonstration_Data_Acquisition -- The principle describing the theoretical basis for expert demonstration acquisition.
• Implementation:Haosulab_ManiSkill_Replay_Trajectory_CLI -- The next step: replaying downloaded trajectories with different observation and control modes.
• Implementation:Haosulab_ManiSkill_ManiSkillTrajectoryDataset -- Loading the downloaded/converted trajectories into PyTorch Datasets.
• Environment:Haosulab_ManiSkill_Python_SAPIEN_Core