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
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.