{"id":56115,"plugin_id":"plugins_6abf4e8b66808191af07692fd78a9110","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-26T18:06:39.457Z","digest":"5f68611a0216828679e58f9ea74be9f0e567c5433eb043648fb12ab7c88cdc19","against":null,"payload":{"description":"Create a Valohai project, link it to a local directory, and run executions or pipelines using the Valohai CLI. Use this skill when a user wants to set up a new Valohai project, link an existing project, run a step execution, run a pipeline, watch execution logs, or manage their Valohai project via the CLI. Triggers on mentions of vh project create, vh execution run, vh pipeline run, running on Valohai, or Valohai CLI commands.","included_files":[],"name":"valohai-project-run","skill_md_contents":"---\nname: valohai-project-run\ndescription: Create a Valohai project, link it to a local directory, and run executions or pipelines using the Valohai CLI. Use this skill when a user wants to set up a new Valohai project, link an existing project, run a step execution, run a pipeline, watch execution logs, or manage their Valohai project via the CLI. Triggers on mentions of vh project create, vh execution run, vh pipeline run, running on Valohai, or Valohai CLI commands.\nlicense: Apache-2.0\nmetadata:\n  author: valohai\n  version: \"1.0\"\n  compatibility: Requires valohai-cli installed (pip install valohai-cli). Designed for Claude Code or similar AI coding agents.\n---\n\n# Valohai Project Setup and Execution\n\nSet up a Valohai project and run ML steps using the Valohai CLI (`vh`). This covers project creation, linking, running executions, running pipelines, and monitoring jobs.\n\n## Prerequisites\n\n```shell\n# Install the CLI\npip install valohai-cli\n\n# Login (interactive)\nvh login\n\n# Login with token (for SSO or CI/CD)\nvh login --token YOUR_TOKEN\n\n# Login to self-hosted instance\nvh login --host https://your-company.valohai.io --token YOUR_TOKEN\n```\n\n## Step-by-Step: Project Setup\n\n### 1. Create a New Project\n\n```shell\n# Create and link to current directory\nvh project create --name my-ml-project\n\n# Create with description\nvh project create --name my-ml-project --description \"Image classification pipeline\"\n\n# Create under an organization (CASE SENSITIVE - must match exactly)\nvh project create --name my-ml-project --owner my-org\n\n# Create under an organization team (CASE SENSITIVE)\nvh project create --name my-ml-project --owner my-org:ml-team\n\n# Create without linking\nvh project create --name my-ml-project --no-link\n```\n\nThis creates the project on Valohai and links the current directory to it.\n\n### 2. Link to an Existing Project\n\n```shell\n# Interactive selection from your projects\nvh project link\n\n# Or specify directly\nvh project link --project my-org/my-ml-project\n```\n\n### 3. Check Project Status\n\n```shell\n# See current project link\nvh project status\n\n# List all your projects\nvh project list\n\n# Open project in browser\nvh project open\n```\n\n## Step-by-Step: Running Executions\n\n### 1. Run a Step (Ad-hoc)\n\nDuring development, use `--adhoc` to run local code without Git commits:\n\n```shell\n# Basic run with local code\nvh execution run train-model --adhoc\n\n# Run and watch logs in real-time\nvh execution run train-model --adhoc --watch\n\n# Run with parameter overrides\nvh execution run train-model --adhoc --epochs=100 --learning_rate=0.0001\n\n# Run with input overrides\nvh execution run train-model --adhoc --training-data=s3://bucket/new-data.csv\n\n# Run with specific Docker image override\nvh execution run train-model --adhoc --image pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime\n\n# Run with environment override\nvh execution run train-model --adhoc --environment aws-eu-west-1-p3-2xlarge\n\n# Run with tags\nvh execution run train-model --adhoc --tag experiment-v2 --tag baseline\n\n# Run with title\nvh execution run train-model --adhoc --title \"Baseline experiment with new data\"\n\n# Run with environment variables\nvh execution run train-model --adhoc --var WANDB_MODE=disabled\n\n# Combine multiple options\nvh execution run train-model --adhoc --watch \\\n  --epochs=100 \\\n  --learning_rate=0.0001 \\\n  --training-data=s3://bucket/v2/train.csv \\\n  --tag baseline-v2\n```\n\n### 2. Run from a Git Commit\n\nWhen code is committed and pushed:\n\n```shell\n# Run from latest fetched commit\nvh execution run train-model\n\n# Run from specific commit\nvh execution run train-model --commit abc123\n\n# Run from a branch/tag\nvh execution run train-model --commit main\n```\n\n### 3. Monitor Executions\n\n```shell\n# List recent executions\nvh execution list\nvh execution list --count 10\n\n# Stream logs from an execution\nvh execution logs <counter-or-id> --stream\n\n# Watch a running execution\nvh execution watch <counter-or-id>\n\n# Get execution details\nvh execution info <counter-or-id>\n\n# Open execution in browser\nvh execution open <counter-or-id>\n\n# List execution outputs\nvh execution outputs <counter-or-id>\n\n# Download outputs\nvh execution outputs <counter-or-id> --download ./local-dir/\n\n# Stop a running execution\nvh execution stop <counter-or-id>\n```\n\n### 4. See Available Steps\n\n```shell\n# List steps in current commit\nvh execution run\n# (Without a step name, it shows available steps)\n```\n\n## Step-by-Step: Running Pipelines\n\n### 1. Run a Pipeline\n\n```shell\n# Run pipeline with local code\nvh pipeline run my-pipeline --adhoc\n\n# Run from Git\nvh pipeline run my-pipeline\n\n# Run with title and tags\nvh pipeline run my-pipeline --adhoc --title \"Full training run\" --tag weekly\n\n# Override node parameters\nvh pipeline run my-pipeline --adhoc --train-node.epochs=200\n\n# Override node inputs\nvh pipeline run my-pipeline --adhoc --train-node.dataset=s3://bucket/v2/\n\n# Override pipeline-level parameters\nvh pipeline run my-pipeline --adhoc --learning_rate=0.0001\n\n# Override environment for all nodes\nvh pipeline run my-pipeline --adhoc --environment aws-eu-west-1-p3-2xlarge\n```\n\n### 2. Monitor Pipelines\n\n```shell\n# List pipelines\nvh pipeline list\n\n# Stop a pipeline\nvh pipeline stop <counter-or-id>\n```\n\n### 3. Debug Failed Pipeline Executions\n\n**CRITICAL: Pipeline numbers and execution numbers are different things.** A pipeline contains multiple executions (one per node). When a pipeline fails, you must find and inspect the **specific failed execution**, not the pipeline itself.\n\n```shell\n# WRONG - this is the pipeline number, not an execution number\nvh execution logs 42 --stream\n\n# CORRECT workflow:\n# 1. Open the pipeline in the browser to see which node failed\nvh pipeline list\n\n# 2. List executions to find the ones belonging to your pipeline\nvh execution list\n\n# 3. Stream logs from the specific EXECUTION that failed (not the pipeline number)\nvh execution logs <execution-counter> --stream\n\n# 4. Get details about the failed execution\nvh execution info <execution-counter>\n```\n\nEach node in a pipeline creates its own execution with its own counter number. Always use the execution counter (visible in the execution list or the web UI) when fetching logs, not the pipeline counter.\n\n## Step-by-Step: Complete Workflow\n\nHere's the full workflow from zero to running:\n\n```shell\n# 1. Create project directory\nmkdir my-ml-project && cd my-ml-project\n\n# 2. Create Valohai project\nvh project create --name my-ml-project\n\n# 3. Create your training script (train.py)\n# 4. Create valohai.yaml (see valohai-yaml-step skill)\n\n# 5. Validate the YAML\nvh lint\n\n# 6. Run your first execution\nvh execution run train-model --adhoc --watch\n\n# 7. View results in browser\nvh execution open\n\n# 8. Run with different parameters\nvh execution run train-model --adhoc --watch --epochs=100 --learning_rate=0.0001\n\n# 9. Once satisfied, commit and push code\ngit add . && git commit -m \"Add Valohai configuration\"\ngit push origin main\n\n# 10. Fetch latest commit on Valohai\nvh project fetch\n\n# 11. Run from Git (reproducible)\nvh execution run train-model --watch\n```\n\n## YAML Management\n\n**IMPORTANT**: Always run `vh lint` after any change to `valohai.yaml`. This is the first thing to try when executions fail due to configuration issues. It validates syntax, checks references, and catches common mistakes.\n\n```shell\n# Validate valohai.yaml - run this after every YAML change\nvh lint\n\n# Generate YAML step from a Python file (if using valohai-utils)\nvh yaml step train.py\n\n# Generate pipeline YAML from Python pipeline definition\nvh yaml pipeline pipeline.py\n```\n\n## Other Useful Commands\n\n```shell\n# List available environments\nvh environments\n\n# List project commits\nvh project commits\n\n# List data/files in the project\nvh data list\n\n# List project aliases\nvh alias list\n\n# Manage environment variables\nvh project env-var list\nvh project env-var create MY_VAR=value\nvh project env-var delete MY_VAR\n\n# List tasks (hyperparameter sweeps)\nvh task list\nvh task stop <id>\n```\n\n## Common Workflows\n\n### Quick Iteration Loop\n\n```shell\n# Edit code → run → check results → repeat\nvh execution run train-model --adhoc --watch\n# (Make changes to code)\nvh execution run train-model --adhoc --watch --epochs=200\n```\n\n### Hyperparameter Comparison\n\n```shell\n# Run multiple experiments\nvh execution run train-model --adhoc --tag lr-001 --learning_rate=0.001\nvh execution run train-model --adhoc --tag lr-0001 --learning_rate=0.0001\nvh execution run train-model --adhoc --tag lr-00001 --learning_rate=0.00001\n\n# Compare in the web UI\nvh project open\n```\n\n### Pipeline Development\n\n```shell\n# Test individual steps first\nvh execution run preprocess-data --adhoc --watch\nvh execution run train-model --adhoc --watch\n\n# Then run the full pipeline\nvh pipeline run training-pipeline --adhoc\n```\n\n## Edge Cases\n\n- `--adhoc` packages and uploads your local working directory - ensure no large files or secrets are present (use `.valohaiignore` to exclude files)\n- Parameters and inputs are passed as `--name=value` after the step name\n- The CLI auto-detects parameters vs inputs: URLs (containing `://`) are treated as input overrides\n- Without `--watch`, the command returns immediately after queuing the execution\n- `vh lint` validates YAML syntax but doesn't check if Docker images or environments exist\n- For remote-only projects (no local Git), omit `--adhoc` and use `--commit`\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}