--- title: CLI Job Management description: 'Run a tool with key=value parameters, then follow, stream or watch it, read its JSON with jobs results, save artifacts with jobs download, or cancel it.' tags: - jobs - monitoring - results - automation --- intermediate The ivybloom CLI is the scriptable surface for the platform, and job management is how you submit, monitor, and manage individual computational jobs directly from the command line. Reach for these commands whenever a scripted pipeline needs to launch a single tool run — such as a fold or docking job — and track it through to results without the web interface. Jobs are the building blocks that batch and workflow automation compose over; for the full command surface, see the [CLI overview](/docs/cli). ## Job Management Submit, monitor, and manage computational jobs from the command line. --- ## Submitting Jobs ### Single Job Submission Submit a job with the `run` command using `key=value` parameters: ```bash ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA ``` ### With Options ```bash # Follow job progress after submission ivybloom run esmfold protein_sequence=MKLVFFAEDV... --follow # Give the job a name ivybloom run esmfold protein_sequence=MKLVFFAEDV... --name "my-protein" # Assign to a project ivybloom run esmfold protein_sequence=MKLVFFAEDV... --project-id proj_123 # Dry run (validate without submitting) ivybloom run esmfold protein_sequence=MKLVFFAEDV... --dry-run ``` ### Interactive and Wait Modes ```bash # Interactive form-based submission ivybloom run esmfold --interactive # Wait for completion with polling ivybloom run esmfold protein_sequence=MK --wait --timeout 30m --poll-interval 10s # Pre-flight health check before submission ivybloom run esmfold protein_sequence=MK --preflight # Dry-run levels: syntax, quick, full ivybloom run esmfold protein_sequence=MK --dry-run --dry-run-mode full ``` ### Validation Modes Use `--dry-run-mode` for different validation levels: ```bash # Syntax validation only ivybloom run esmfold protein_sequence=MKLVFFAEDV... --dry-run-mode syntax # Quick validation (checks parameter types) ivybloom run esmfold protein_sequence=MKLVFFAEDV... --dry-run-mode quick # Full validation (includes API checks) ivybloom run esmfold protein_sequence=MKLVFFAEDV... --dry-run-mode full ``` --- ## Monitoring Jobs ### List All Jobs ```bash ivybloom jobs list ``` **Filter by status:** ```bash ivybloom jobs list --status running ivybloom jobs list --status completed ivybloom jobs list --status failed ``` **Other options:** ```bash ivybloom jobs list --limit 10 ivybloom jobs list --format json ivybloom jobs list --animate # Animated output ``` ### Job Details Get detailed information about a specific job: ```bash ivybloom jobs status JOB_ID ``` Output includes: - Current status and progress - Input parameters - Resource usage (CPU, memory, GPU) - Start time and duration - Error messages (if failed) ### Follow Job Progress Monitor a job in real-time: ```bash ivybloom jobs follow JOB_ID ``` **With additional output:** ```bash ivybloom jobs follow JOB_ID --logs # Show job logs ivybloom jobs follow JOB_ID --phase # Show phase transitions ivybloom jobs follow JOB_ID --progress # Show progress updates ivybloom jobs follow JOB_ID --timeout 600 # Set max follow time ``` ### Watch Multiple Jobs Monitor all running jobs: ```bash ivybloom jobs watch ivybloom jobs watch --interval 5 # Refresh every 5 seconds ivybloom jobs watch --include-pending ``` ### Search Jobs `jobs search` opens an interactive fuzzy finder over your jobs: ```bash ivybloom jobs search ivybloom jobs search --multi # select several (requires gum) ``` --- ## Downloading Results ### Download All Results ```bash ivybloom jobs download JOB_ID ``` By default, downloads to the current directory. ### Specify Output Directory ```bash ivybloom jobs download JOB_ID --output ./results ``` ### Download Multiple Jobs ```bash ivybloom jobs download JOB_ID1 JOB_ID2 JOB_ID3 ``` ### AI Analysis of Results Include AI-generated analysis with your download: ```bash ivybloom jobs download JOB_ID --analyze ``` --- ## Fetching Results ### Raw JSON Results View results in the terminal (distinct from `download` which saves artifact files): ```bash ivybloom jobs results JOB_ID ivybloom jobs results JOB_ID --format json ``` ### Results vs Download | Feature | `jobs results` | `jobs download` | |---------|---------------|-----------------| | Output | JSON to stdout | Files to disk | | Use case | View/parse results | Save artifacts | | Format flag | `--format` | N/A | | Output flag | N/A | `--output` directory | --- ## Streaming Stream real-time output from a running job via WebSocket: ```bash ivybloom jobs stream JOB_ID ``` ### Job Monitoring Comparison | Feature | `status` | `follow` | `stream` | `watch` | |---------|----------|----------|----------|---------| | Real-time | No | Yes | Yes | Yes | | Single job | Yes | Yes | Yes | No (all) | | Progress bar | No | Yes | No | No | | WebSocket | No | No | Yes | No | | Exits on complete | N/A | Yes | No | No | --- ## Cloning Jobs Clone an existing job with its original parameters: ```bash ivybloom jobs clone JOB_ID ``` --- ## Filtering There is no `jobs filter` command. Narrow the list with `jobs list` flags: ```bash ivybloom jobs list --status completed --limit 10 ``` ### Search vs List | Feature | `jobs search` | `jobs list` | |---------|--------------|-------------| | Interactive fuzzy search | Yes | No | | Status filter | No | `--status` | | Result limit | No | `--limit` | --- ## Job Lifecycle ### Deprecation Mark jobs as deprecated (hides from default listings without deleting results): ```bash ivybloom jobs deprecate JOB_ID --reason "superseded by job_xyz" ivybloom jobs undeprecate JOB_ID ``` --- ## Managing Jobs ### Cancel a Job Stop a running or queued job: ```bash ivybloom jobs cancel JOB_ID ``` --- ## Job Lifecycle Diagram P[PENDING] P --> R[RUNNING] R --> C[COMPLETED] C --> Res["jobs results (JSON)"] C --> Dl["jobs download (files)"] R --> F[FAILED] P --> X["CANCELLED
(via jobs cancel)"]`} caption="A job moves from PENDING through RUNNING to a terminal state; completed jobs expose results and downloadable files." /> --- ## Job Statuses | Status | Description | |--------|-------------| | `pending` | Job is waiting to be processed | | `running` | Job is currently executing | | `completed` | Job finished successfully | | `failed` | Job encountered an error | | `cancelled` | Job was manually cancelled | --- ## Output Formats Use `--format` to control output. All list and status commands support these formats: **Table (default)** ``` ID TOOL STATUS CREATED job_abc123 esmfold completed 2 hours ago job_def456 admet running 5 minutes ago job_ghi789 diffdock pending just now ``` **JSON** ```json [ {"id": "job_abc123", "tool": "esmfold", "status": "completed", "created_at": "2026-03-08T10:00:00Z"}, {"id": "job_def456", "tool": "admet", "status": "running", "created_at": "2026-03-08T11:55:00Z"}, {"id": "job_ghi789", "tool": "diffdock", "status": "pending", "created_at": "2026-03-08T12:00:00Z"} ] ``` **CSV** ``` id,tool,status,created_at job_abc123,esmfold,completed,2026-03-08T10:00:00Z job_def456,admet,running,2026-03-08T11:55:00Z job_ghi789,diffdock,pending,2026-03-08T12:00:00Z ``` ```bash ivybloom jobs list # Table (default) ivybloom jobs list --format json # JSON ivybloom jobs list --format csv > jobs.csv # CSV export ``` --- ## Interactive Dashboard For visual job monitoring, use the TUI (Terminal User Interface): ```bash ivybloom ``` Features: - Real-time job updates via SSE streaming - Jobs Hub with filtering (`/jobs`) - Context panel showing active jobs - Download artifacts directly See the [Interactive TUI Guide](/docs/cli/tui) for comprehensive keyboard shortcuts and navigation. --- ## CI/CD Integration ### Check Job Status in Scripts ```bash #!/bin/bash # Submit job and capture ID JOB_OUTPUT=$(ivybloom run esmfold protein_sequence=MKLVFFAEDV... --json) JOB_ID=$(echo $JOB_OUTPUT | jq -r '.job_id') # Wait for completion using follow ivybloom jobs follow $JOB_ID --timeout 3600 # Check final status STATUS=$(ivybloom jobs status $JOB_ID --json | jq -r '.status') if [ "$STATUS" = "completed" ]; then echo "Job completed!" ivybloom jobs download $JOB_ID --output ./results else echo "Job failed!" exit 1 fi ``` ### GitHub Actions Example ```yaml - name: Submit Analysis Job env: IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }} run: | JOB_OUTPUT=$(ivybloom run esmfold protein_sequence=MKLVFFAEDV... --json) JOB_ID=$(echo $JOB_OUTPUT | jq -r '.job_id') echo "JOB_ID=$JOB_ID" >> $GITHUB_ENV - name: Wait for Results env: IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }} run: | ivybloom jobs follow $JOB_ID --timeout 3600 ivybloom jobs download $JOB_ID --output ./results ``` --- > For CI/CD automation, add `--agent` for structured JSON output. See [Agent Mode](/docs/cli/agent-mode) for the full envelope schema. --- ## Read next - [Batch Processing](/docs/cli/batch) — Run multiple jobs in parallel - [Compounds](/docs/cli/compounds) — Screen compound libraries - [Agent Mode](/docs/cli/agent-mode) — CI/CD automation - [Commands Reference](/docs/cli/commands) — Full command documentation