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.

Difficulty

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.

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:

ivybloom run esmfold protein_sequence=MKLVFFAEDVGSNKGAIIGLMVGGVVIA

With Options

# 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

# 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:

# 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

ivybloom jobs list

Filter by status:

ivybloom jobs list --status running
ivybloom jobs list --status completed
ivybloom jobs list --status failed

Other options:

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:

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:

ivybloom jobs follow JOB_ID

With additional output:

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:

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:

ivybloom jobs search
ivybloom jobs search --multi   # select several (requires gum)

Downloading Results

Download All Results

ivybloom jobs download JOB_ID

By default, downloads to the current directory.

Specify Output Directory

ivybloom jobs download JOB_ID --output ./results

Download Multiple Jobs

ivybloom jobs download JOB_ID1 JOB_ID2 JOB_ID3

AI Analysis of Results

Include AI-generated analysis with your download:

ivybloom jobs download JOB_ID --analyze

Fetching Results

Raw JSON Results

View results in the terminal (distinct from download which saves artifact files):

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:

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:

ivybloom jobs clone JOB_ID

Filtering

There is no jobs filter command. Narrow the list with jobs list flags:

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):

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:

ivybloom jobs cancel JOB_ID

Job Lifecycle Diagram

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:

ID          TOOL      STATUS     CREATED
job_abc123  esmfold   completed  2 hours ago
job_def456  admet     running    5 minutes ago
job_ghi789  diffdock  pending    just now

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):

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 for comprehensive keyboard shortcuts and navigation.

CI/CD Integration

Check Job Status in Scripts

#!/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

- 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 for the full envelope schema.

CLI Job Management