Hephaes CLI

hephaes is the official command-line interface for Hephaes — a version-controlled dataset platform for robotics and machine learning teams. Use it to upload, version, and download datasets without leaving your terminal.

Install

pip install hephaes-cli

Requires Python 3.10+.

Quick Start

# 1. Log in
hephaes login

# 2. Create a repo (or select an existing one)
hephaes repo create "My Dataset" --format parquet
hephaes repo use my-dataset

# 3. Stage files, commit, and push
hephaes add data/train.parquet data/val.parquet
hephaes commit -m "Initial upload"
hephaes push

# 4. Download on another machine
hephaes repo use my-dataset
hephaes pull --target ./dataset

Commands

Authentication

hephaes login                   # Authenticate (prompts for email + password)
hephaes logout                  # Remove the local session
hephaes whoami                  # Show the currently authenticated user

Credentials are stored securely in the OS keychain (macOS Keychain, Windows Credential Manager, etc).

Repositories

hephaes repo list                          # List all repos you have access to
hephaes repo create "Name" --format parquet  # Create a new repo
hephaes repo use <slug>                    # Set the active repo for subsequent commands
hephaes repo current                       # Show the active repo
hephaes repo info [<slug>]                 # Show details for a repo

Staging & Versioning

Hephaes uses a git-like workflow: stage files, create a local commit manifest, then push to the remote.

hephaes add <file> [<file> ...]   # Stage files for the next commit
hephaes status                    # Show staged files
hephaes reset [<file> ...]        # Unstage files (or clear everything)
hephaes commit -m "message"       # Create a local commit manifest
hephaes push                      # Upload staged files and publish the commit

Inspecting Commits

hephaes log                       # List commits for the active repo
hephaes ls                        # List files in the latest commit
hephaes metrics                   # Show dataset-level metrics for the latest commit
hephaes episodes                  # List episodes in the latest commit
hephaes episode-metrics           # Show per-episode metrics
hephaes jobs                      # Show processing jobs for the active repo
hephaes activity                  # Show recent activity for the active repo
hephaes activity --all            # Show activity across all repos

Pass --commit <id> to any of these to inspect a specific commit rather than HEAD.

Downloading

hephaes pull                          # Download all files from the latest commit
hephaes pull --target ./data          # Download into a specific directory
hephaes pull --commit <id>            # Download a specific commit
hephaes pull --path train.parquet     # Download a single file

Collaborators

hephaes repo members list                                      # List collaborators
hephaes repo members add --email user@example.com --role editor  # Invite by email
hephaes repo members add --user-id <uuid> --role viewer          # Invite by user ID
hephaes repo members update <user-id> --role viewer              # Change role
hephaes repo members remove <user-id>                            # Remove collaborator

Roles: owner (full control), editor (upload/commit, no member management), viewer (read-only).

Account

hephaes account usage    # Show your plan, storage usage, and repo limits

Options

Most commands accept --repo <slug> to target a specific repo without switching the active context.

All commands support --output json (or -o json) for machine-readable output, with non-zero exit codes and structured error payloads on failure:

hephaes --output json repo list
hephaes --output json log --repo my-dataset

CI / Headless Use

For non-interactive environments (GitHub Actions, Docker, etc.), inject a token instead of running login:

export HEPHAES_ACCESS_TOKEN="<token>"
hephaes --output json whoami

Injected tokens are never written to disk or the keychain.