Nuuduu

Python SDK and CLI for Nuuduu Atlas — search, bundle, request, and sync robotics training datasets (LeRobot, MCAP, HEVC) to your local machine for PyTorch / LeRobot workflows.

The CLI talks to the API at nuuduu.com. Browse episodes in the Atlas web app. v1 may still send you to the web app for some bundle payments; the destination is fully in-CLI purchase via nuuduu request (see Roadmap).

Source repository: bitbucket.org/nuuduu/nuuduu

Installation

# Library only
pip install nuuduu

# Library + CLI command (quote brackets so the shell does not treat them as globs)
pip install 'nuuduu[cli]'

Development install:

git clone git@bitbucket.org:nuuduu/nuuduu.git
cd nuuduu
uv sync --all-extras

Workflow

search  →  bundle  →  sync
              ↓
         request (if you need more episodes than the library has)

1. Search — find episodes matching a task description and optional country filter
2. Bundle — server packages matching episodes into a downloadable archive (lerobot by default)
3. Sync — download ready bundles to your local dataset directory
4. Request — order new episodes to be collected when the library does not have enough (--min-episodes on bundle does this automatically)

Quick start (CLI)

# Authenticate (saves token to ~/.config/nuuduu/config.toml, mode 0600)
nuuduu auth login

# Search episodes
nuuduu episodes search --text "pick up cup"

# Bundle episodes matching a search (server-side packaging job)
nuuduu episodes bundle --text "pick up cup"

# Need 10k episodes but the library only has 6k — bundle what's available, request the rest
nuuduu episodes bundle --text "shirt folding" --country fi,ee --min-episodes 10000

# Request new training data directly (quote + confirm — API coming soon)
nuuduu request --text "pick and place red blocks" --episodes 1000 --country fi,ee

# Sync ready bundles to your local dataset directory
nuuduu sync

# Load in LeRobot (after sync)
python -c "
from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
dataset = LeRobotDataset('local', root='~/.cache/huggingface/lerobot/nuuduu-atlas/<download-uuid>')
print(len(dataset))
"

Quick start (library)

from nuuduu import NuuduuAtlas

atlas = NuuduuAtlas.from_config()

# Bundle what's in the library; request any shortfall
bundle = atlas.bundle_episodes(
    text="shirt folding",
    country="fi,ee",
    min_episodes=10000,
    confirm_request=True,
)
print(bundle.bundled_episodes, "bundled,", bundle.requested_episodes, "requested")

result = atlas.sync(format="lerobot")
for item in result.synced:
    print(item.path)

Authentication

Use the same email and password as your Atlas web app account. The CLI authenticates against the API at https://nuuduu.com with type=api.

Credentials are stored at ~/.config/nuuduu/config.toml with 0600 permissions. The CLI refuses to read config files that are group- or world-readable.

nuuduu auth login              # email + password → saves token
nuuduu auth logout             # clear saved token
nuuduu auth token set TOKEN    # set token manually
nuuduu auth status             # show masked token status

Tokens expire after 24 hours in production. On HTTP 401, run nuuduu auth login again.

Dataset directory

Resolved automatically via priority chain:

1. --dataset-dir CLI flag
2. NUUDUU_DATASET_DIR environment variable
3. dataset_dir in config file
4. HF_LEROBOT_HOME/nuuduu-atlas (LeRobot ecosystem default)
5. Project .env, training configs, or ./datasets/nuuduu-atlas
6. Fallback: ~/.cache/huggingface/lerobot/nuuduu-atlas

nuuduu config show   # shows resolved path and source

Local layout:

{dataset_dir}/
  .nuuduu/manifest.json
  lerobot/{download_uuid}/     # LeRobot v2.1 dataset
  mcap/{download_uuid}/        # per-episode .mcap files
  hevc/{download_uuid}/        # per-episode .mp4 files

CLI reference

nuuduu --help
nuuduu --version

nuuduu auth login
nuuduu auth logout
nuuduu auth token set TOKEN
nuuduu auth status

nuuduu config show
nuuduu config set KEY VALUE

nuuduu sync [--dataset-dir PATH] [--format lerobot|mcap|hevc|all] [--dry-run] [--verify]

nuuduu episodes search [--text QUERY] [--country fi,ee] [--limit N]
nuuduu episodes latest [--limit N]
nuuduu episodes bundle [--text QUERY] [--country fi,ee] [--limit N] \
  [--min-episodes N] [--format lerobot|mcap|hevc] [--uuids UUID[,UUID...]] \
  [--wait] [--yes]

nuuduu request --text "TASK" --episodes N [--country fi,ee] [--yes]
nuuduu request list

Add --json to any command for machine-readable output.

Shared search options

These options work the same on episodes search, episodes bundle, and request:

Bundle-specific options

Roadmap

v1 (today): Search episodes, bundle matching episodes on the server, then nuuduu sync to download ready bundles locally. Some paid bundles still require completing payment in the Atlas web app before nuuduu sync.

Destination UX — order new data entirely from the terminal:

nuuduu request --text "pick and place red blocks" --episodes 1000

Estimated price: €742
Available immediately: 681 episodes
To collect: 319 episodes

Purchase using Acme Robotics account? [Y/n]

After confirmation, Atlas fulfills the order and nuuduu sync materializes bundles locally. No browser step.

Download formats

Integrity verification

When the Atlas API provides a hash field (SHA256 of the bundle zip), nuuduu sync:

1. Verifies the downloaded zip before extracting
2. Stores the hash in .nuuduu/manifest.json
3. Skips re-download when the local hash matches

nuuduu sync --verify   # re-check local bundles without downloading

Library API

Key methods on NuuduuAtlas:

Exceptions: AuthError, ApiError, IntegrityError, ConfigError, NotFoundError

Progress callbacks for sync:

from nuuduu.types import SyncProgressEvent

def on_progress(event: SyncProgressEvent) -> None:
    print(event.phase, event.bytes_done, event.bytes_total)

atlas.sync(on_progress=on_progress)

Troubleshooting

Development

uv sync --all-extras
uv run pytest
uv build

See CONTRIBUTING.md for release and contribution guidelines.

CI runs on Bitbucket Pipelines for every push and pull request.

Publishing

# Bump version in pyproject.toml and CHANGELOG.md
uv build
git tag v0.4.0 && git push origin v0.4.0   # triggers Bitbucket Pipeline PyPI publish

One-time setup: add a secured PYPI_TOKEN repository variable in Bitbucket → Repository settings → Pipelines → Repository variables.

Legal

Copyright © 2026 Nuuduu UAB. Licensed under the MIT License.

Nuuduu® is a registered trademark of Nuuduu UAB. All rights reserved. The Nuuduu name and logo may not be used to imply endorsement or affiliation without prior written permission from Nuuduu UAB.