client/README.md

# Art DAG Client

CLI for interacting with the Art DAG L1 rendering server.

## Setup

```bash
pip install -r requirements.txt
```

## Configuration

```bash
# Set L1 server URL (default: http://localhost:8100)
export ARTDAG_SERVER=http://localhost:8100

# Set L2 server URL for auth (default: http://localhost:8200)
export ARTDAG_L2=https://artdag.rose-ash.com

# Or pass with commands
./artdag.py --server http://localhost:8100 --l2 https://artdag.rose-ash.com <command>
```

## Authentication

Most commands require authentication. Login credentials are stored locally in `~/.artdag/token.json`.

```bash
# Register a new account
artdag register <username> [--email user@example.com]

# Login
artdag login <username>

# Check current user
artdag whoami

# Logout
artdag logout
```

## Commands Reference

### Server & Stats

```bash
# Show server info
artdag info

# Show user stats (counts of runs, recipes, effects, media, storage)
artdag stats

# List known named assets
artdag assets
```

### Runs

```bash
# List runs (with pagination)
artdag runs [--limit N] [--offset N]

# Start a run
artdag run <recipe> <input_cid> [--name output_name] [--wait]

# Get run status
artdag status <run_id>

# Get detailed run info
artdag status <run_id> --plan       # Show execution plan with steps
artdag status <run_id> --artifacts  # Show output artifacts
artdag status <run_id> --analysis   # Show audio analysis data

# Delete a run
artdag delete-run <run_id> [--force]
```

### Recipes

```bash
# List recipes (with pagination)
artdag recipes [--limit N] [--offset N]

# Show recipe details
artdag recipe <recipe_id>

# Upload a recipe (YAML or S-expression)
artdag upload-recipe <filepath>

# Run a recipe with inputs
artdag run-recipe <recipe_id> -i node_id:cid [--wait]

# Delete a recipe
artdag delete-recipe <recipe_id> [--force]
```

### Effects

```bash
# List effects (with pagination)
artdag effects [--limit N] [--offset N]

# Show effect details
artdag effect <cid>

# Show effect with source code
artdag effect <cid> --source

# Upload an effect (.py file)
artdag upload-effect <filepath>
```

### Media / Cache

```bash
# List cached content (with pagination and type filter)
artdag cache [--limit N] [--offset N] [--type all|image|video|audio]

# View/download cached content
artdag view <cid>                    # Show info
artdag view <cid> -o output.mp4     # Download to file
artdag view <cid> -o - | mpv -      # Pipe to player

# Upload file to cache and IPFS
artdag upload <filepath>

# Import local file to cache (local server only)
artdag import <filepath>

# View/update metadata
artdag meta <cid>                              # View metadata
artdag meta <cid> -d "Description"             # Set description
artdag meta <cid> -t "tag1,tag2"               # Set tags
artdag meta <cid> --publish "my-video"         # Publish to L2

# Delete cached content
artdag delete-cache <cid> [--force]
```

### Storage Providers

```bash
# List storage providers
artdag storage list

# Add a provider (interactive)
artdag storage add <type> [--name friendly_name] [--capacity GB]
# Types: pinata, web3storage, nftstorage, infura, filebase, storj, local

# Test provider connectivity
artdag storage test <id>

# Delete a provider
artdag storage delete <id> [--force]
```

### Folders & Collections

```bash
# Folders
artdag folder list
artdag folder create <path>
artdag folder delete <path>

# Collections
artdag collection list
artdag collection create <name>
artdag collection delete <name>
```

### v2 API (3-Phase Execution)

```bash
# Generate execution plan
artdag plan <recipe_file> -i name:cid [--features beats,energy] [--output plan.json]

# Execute a plan
artdag execute-plan <plan_file> [--wait]

# Run recipe (plan + execute in one step)
artdag run-v2 <recipe_file> -i name:cid [--wait]

# Check v2 run status
artdag run-status <run_id>
```

### Publishing to L2

```bash
# Publish a run output to L2
artdag publish <run_id> <output_name>
```

### Data Management

```bash
# Clear all user data (preserves storage configs)
artdag clear-data [--force]
```

## Example Workflows

### Basic Rendering

```bash
# Login
artdag login myuser

# Check available assets
artdag assets

# Run an effect on an input
artdag run dog cat --wait

# View runs
artdag runs

# Download result
artdag view <output_cid> -o result.mp4
```

### Recipe-Based Processing

```bash
# Upload a recipe
artdag upload-recipe my-recipe.yaml

# View recipes
artdag recipes

# Run with inputs
artdag run-recipe <recipe_id> -i video:bafkrei... --wait

# View run plan
artdag status <run_id> --plan
```

### Managing Storage

```bash
# Add Pinata storage
artdag storage add pinata --name "My Pinata"

# Test connection
artdag storage test 1

# View all providers
artdag storage list
```

### Browsing Media

```bash
# List all media
artdag cache

# Filter by type
artdag cache --type video --limit 20

# View with pagination
artdag cache --offset 20 --limit 20
```