Metadata-Version: 2.4
Name: hephaes-cli
Version: 0.1.0
Summary: Terminal-first workflows for Hephaes datasets
License: MIT
Keywords: cli,datasets,hephaes,robotics
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# Hephaes CLI

`hephaes` is the official command-line interface for [Hephaes](https://hephaes.com) — a version-controlled dataset platform for robotics and machine learning teams. Use it to upload, version, and download datasets without leaving your terminal.

## Install

```bash
pip install hephaes-cli
```

Requires Python 3.10+.

## Quick Start

```bash
# 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

```bash
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

```bash
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.

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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`:

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

Injected tokens are never written to disk or the keychain.
