👋Welcome to Flow, our task CLI

Welcome to the Flow CLI documentation. This guide will help you understand how to use the Flow Command-Line Interface to manage your Foundry tasks and instances efficiently.

Note: the Foundry Flow Task SDK and CLI is currently in preview. Please message us in your dedicated Foundry Slack channel to request access, and we will send right away.

The Flow CLI is a command-line tool designed to help you manage tasks and instances on Foundry.

With Flow CLI, you can submit new tasks, check the status of existing tasks, and cancel tasks as needed.

It provides an easy-to-use interface for interacting with Foundry's APIs, streamlining your workflow.

Table of Contents

💡Installation

We've put together some helpful guides for you to get setup with our product quickly and easily.

Commands

The Flow CLI supports the following commands:

  • submit: Submit a new 'task' to Foundry.

  • status: Check the status of tasks and instances.

  • cancel: Cancel an existing task, and delete it's instance and ephemeral storage, keeping persistent storage.

We will say more about the specific options and arguments that you can use to control each command's behavior below.

Submit

Use the submit command to submit a new task to Foundry. This command requires a configuration YAML file that specifies the task details.

Usage:

flow submit path/to/config.yaml [options]

Status

Use the status command to check the status of your tasks and instances.

Usage:

flow status [options]

Options:

  • --task-name: show the status of just one task → name of the task to filter on.

  • --format: Output format for the command. Choices are table, json, yaml, or plain. Default is table.

  • --show-all: Show all entries, including terminated tasks; by default, we show the last 5 tasks

Cancel

Use the cancel command to cancel an existing task.

Usage:

flow cancel --task-name TASK_NAME [options]

Options:

  • --task-name: (Required) Name of the task to cancel.

Task configuration file

When submitting a task using the submit command, you need to provide a configuration YAML file. This file specifies all the necessary details for your task, such as resource requirements, startup scripts, persistent storage and ports config, and more.

Example Configuration

Below is an example configuration file flow_example.yaml:

# -------------------------------------------------------------------------
# Foundry Task Configuration
# -------------------------------------------------------------------------
# This file provides a comprehensive configuration for defining a Foundry task.
# Each section explains both required and optional fields, guiding you in
# tailoring your workflow. Update or uncomment fields according to your needs.

# -------------------------------------------------------------------------
# [1] Task Name (Optional)
# -------------------------------------------------------------------------
# A human-readable, descriptive name for this task. Appears in Foundry UIs.
# If omitted, a default or auto-generated name may be used.
name: foundry-flow-example-batch-task

# -------------------------------------------------------------------------
# [2] Foundry Task Management
# -------------------------------------------------------------------------
# Parameters for how Foundry schedules, prices, and manages this task.
task_management:

  # -----------------------------------------------------------------------
  # 2.1 Priority (Optional)
  # -----------------------------------------------------------------------
  # Defines a shorthand for setting a utility price threshold.
  # Foundry uses these utility thresholds to optimize global utility across all tasks.
  # Valid options: [critical, high, standard, low].
  # If not specified, defaults to 'standard' or the configured default in the 'flow_config' file
  # Set values in the 'flow_config' file to override defaults.
  priority: low  # Example for lower priority 'batch' tasks

  # -----------------------------------------------------------------------
  # 2.2 Explicit Utility Threshold Price (Optional)
  # -----------------------------------------------------------------------
  # A direct per-GPU limit price (spot_bid). If left out, Foundry calculates
  # the spot_bid based on the 'priority' field above. 
  # Note, Foundry utility maximization is mbased on a second price auction, so users aren't charged their utility price but rather a guaranteed lower rate.
  # Thus, users can set the utility threshold price to their 'true utility threshold'.
  utility_threshold_price: 2.24  # Example low priority custom price for a batch task

# -------------------------------------------------------------------------
# [3] Resource Configuration
# -------------------------------------------------------------------------
# Specify the compute resources needed for the task.
resources_specification:

  # -----------------------------------------------------------------------
  # 3.1 Instance Type
  # -----------------------------------------------------------------------
  # The name of the GPU instance type. Adjust according to your project's
  # performance requirements or availability in a given Foundry cluster.
  fcp_instance: h100-80gb.SXM

  # -----------------------------------------------------------------------
  # 3.2 Number of Instances
  # -----------------------------------------------------------------------
  # Total instances to request. By default, a single instance is allocated.
  # Increase for tasks that need multi-instance processing in an all-or-nothing
  # configuration (e.g., distributed training).
  num_instances: 1

  # -----------------------------------------------------------------------
  # 3.3 Cluster ID (Optional)
  # -----------------------------------------------------------------------
  # Restrict task placement to a specific cluster or region if needed.
  # Uncomment and set the cluster_id to choose a region (e.g., "us-central1").
  # cluster_id: us-central1

# -------------------------------------------------------------------------
# [4] Ports to Expose (Optional)
# -------------------------------------------------------------------------
# Define which ports or port ranges to expose for external access, such as for
# Jupyter or TensorBoard. You can specify single ports (e.g., "8080"), ranges
# (e.g., "6006-6010"), or pair external and internal ports explicitly.
ports:
  - 8080              # Single port exposed externally and internally
  - 6006-6010         # Expose port range externally and internally
  # You can also map external ports to different internal ports or ranges:
  - external: 8441
    internal: 8001
  - external: 8442
    internal: 8002
  - external: 8443-8445
    internal: 8003-8005

# -------------------------------------------------------------------------
# [5] Storage Configuration (Optional)
# -------------------------------------------------------------------------
# Configure persistent storage volumes to be mounted on the task instance.
# This is particularly useful for sharing data, storing checkpoints, or
# accessing large datasets. Uncomment and fill out the relevant fields.

persistent_storage:
  # -----------------------------------------------------------------------
  # 5.1 Create a New Volume (Optional)
  # -----------------------------------------------------------------------
  # Provide the desired volume name, size, type, region, and mount point.
  create:
    volume_name: my-new-volume           # Custom label for your volume
    storage_type: block                  # Options: 'block' or 'nfs'
    size: 1                              # Size in GB
    mount_point: /mnt/my-new-volume      # Where volume is mounted on the instance
    region_id: us-central1-a             # Region/zone for storage
    disk_interface: Block                # Usually 'Block' for block-based volumes

  # -----------------------------------------------------------------------
  # 5.2 Attach an Existing Volume (Optional)
  # -----------------------------------------------------------------------
  # Instead of creating a new volume, attach an existing one by name.
  # Uncomment and fill out to attach your pre-existing storage.
  # attach:
  #   volume_name: existing-volume-name
  #   mount_point: /mnt/existing-volume

# -------------------------------------------------------------------------
# [6] Startup Script (Optional)
# -------------------------------------------------------------------------
# Provide commands that will execute upon instance initialization, enabling
# you to install dependencies or run initial setup tasks automatically.
startup_script: |
  #!/bin/bash
  echo "Starting setup..."
  pip install -r requirements.txt
  echo "Setup complete."

# -------------------------------------------------------------------------
# [7] Versioning
# -------------------------------------------------------------------------
# Indicates the format version of this configuration file.
version: 1

Note: You can copy and adjust this configuration example according to your task requirements.

PreviousInstallationNextFoundry Flow SDK Documentation

Last updated