CLI reference

Installation

Global CLI (uv):
```
uv tool install flow-compute
```
Global CLI (pipx):
```
pipx install flow-compute
```

Overview

Flow CLI & SDK - Submit and manage GPU tasks. Flow helps you provision GPU instances/clusters, run workloads from YAML or command, and monitor/manage tasks end-to-end.

Usage: flow [OPTIONS] COMMAND [ARGS]...

Global Options:

-V, --version - Show version and exit
-h, --help - Show this message and exit
--all - Display full command list in help output
--mode [infra|research] - Switch mode

Getting Started

flow setup

Configure credentials and provider settings

Usage: flow setup [OPTIONS]

Options:

--provider TEXT - Provider to use
--api-key TEXT - API key for authentication
--project TEXT - Project name
--api-url TEXT - API endpoint URL
--dry-run - Show configuration without saving
--output FILE - Write dry-run YAML to file (with --dry-run)
-v, --verbose - Show detailed setup information
--reset - Reset configuration to start fresh
--show - Print current resolved configuration and exit
--yes - Non-interactive; answer yes to prompts (CI)
-h, --help - Show this message and exit

flow docs

Show links to the Flow/Mithril documentation

Usage: flow docs [OPTIONS]

Options:

--verbose - Show additional popular documentation links
--no-open - Don't automatically open browser
-h, --help - Show this message and exit

Compute

flow instance

Manage compute instances

Usage: flow instance [OPTIONS] COMMAND [ARGS]...

Options:

-h, --help - Show this message and exit

flow instance create

Create a new compute instance

Usage: flow instance create [OPTIONS] [CONFIG_FILE] [EXTRA_ARGS]...

Options:

-i, --instance-type TEXT - GPU instance type (e.g., a100, 8xa100, h100)
-r, --region TEXT - Preferred region (e.g., us-west1-b)
-k, --ssh-keys TEXT - Authorized SSH keys (repeatable)
--image TEXT - Docker image to use (default: nvidia/cuda:12.1.0-runtime-ubuntu22.04)
-n, --name TEXT - Task name (default: auto-generated)
--no-unique - Don't append unique suffix to task name
-p, --priority [low|med|high] - Task priority (low/med/high)
--force-new - Force unique task name by appending a suffix
--wait / --no-wait - Wait for task to start running
-d, --dry-run - Validate configuration without submitting
-w, --watch - Watch task progress interactively
--json - Output JSON for automation
--env KEY=VALUE - Environment variables KEY=VALUE (repeatable)
--pricing - Show pricing details in the config table
--slurm - Treat input as a SLURM script
--mount TEXT - Mount storage (format: source or target=source)
--port PORT - Expose a port (repeatable). High ports only (>=1024)
--upload-strategy [auto|embedded|scp|none] - Code upload strategy: auto (default), embedded, scp, or none
--upload-timeout INTEGER - Upload timeout in seconds (default: 600)
--on-upload-failure [continue|fail] - Policy when code upload fails: continue (default) or fail
--upload-code / --no-upload-code - Upload current working directory to the task
-m, --max-price-per-hour FLOAT - Maximum hourly price in USD
-N, --num-instances INTEGER - Number of instances
--distributed [auto|manual] - Distributed rendezvous mode
-v, --verbose - Show detailed configuration guide
-h, --help - Show this message and exit

flow instance delete

Delete compute instances - pattern matching uses wildcards by default

Usage: flow instance delete [OPTIONS] [TASK_IDENTIFIER]

Options:

-y, --yes - Skip confirmation prompt
--all - Cancel all running tasks
-n, --name-pattern TEXT - Cancel tasks matching wildcard pattern (e.g., 'dev-', '-gpu-8x*', 'train-v?'). Use --regex for regex
--regex - Treat pattern as regex instead of wildcard
-v, --verbose - Show detailed examples and patterns
--interactive / --no-interactive - Force interactive selector on/off regardless of terminal autodetect
-h, --help - Show this message and exit

flow instance info

Show detailed information about a specific instance

Usage: flow instance info [OPTIONS] [TASK_IDENTIFIER]

Options:

--all - Show all tasks (default: active tasks only)
-s, --state [pending|open|starting|running|paused|preempting|completed|failed|cancelled] - Filter by task status
--limit INTEGER - Maximum number of tasks to show
--force-refresh - Bypass local caches and fetch fresh task data from provider
--json - Output JSON for automation
--since TEXT - Only tasks created since time (e.g., '2h', '2025-08-07T10:00:00Z')
--until TEXT - Only tasks created until time (same formats as --since)
-v, --verbose - Show detailed status information and filtering examples
-w, --watch - Live update the status display
--compact - Compact allocation view
--refresh-rate FLOAT - Refresh rate in seconds for watch mode (default: 3)
--no-origin-group - Disable Flow/Other grouping in main view
-h, --help - Show this message and exit

flow instance list

List and monitor GPU compute tasks - filter by status, name, or time

Usage: flow instance list [OPTIONS] [TASK_IDENTIFIER]

Options:

--all - Show all tasks (default: active tasks only)
-s, --state [pending|open|starting|running|paused|preempting|completed|failed|cancelled] - Filter by task status
--limit INTEGER - Maximum number of tasks to show
--force-refresh - Bypass local caches and fetch fresh task data from provider
--json - Output JSON for automation
--since TEXT - Only tasks created since time (e.g., '2h', '2025-08-07T10:00:00Z')
--until TEXT - Only tasks created until time (same formats as --since)
-v, --verbose - Show detailed status information and filtering examples
-w, --watch - Live update the status display
--compact - Compact allocation view
--refresh-rate FLOAT - Refresh rate in seconds for watch mode (default: 3)
--no-origin-group - Disable Flow/Other grouping in main view
-h, --help - Show this message and exit

flow volume

Manage persistent storage volumes

Usage: flow volume [OPTIONS] COMMAND [ARGS]...

Options:

-h, --help - Show this message and exit

flow volume list

List all volumes

Usage: flow volume list [OPTIONS]

Options:

-d, --details - Show which tasks use each volume
--json - Output JSON for automation
--region TEXT - Filter volumes by region (default: all)
-h, --help - Show this message and exit

flow volume create

Create a new volume

Usage: flow volume create [OPTIONS]

Options:

-s, --size INTEGER - Volume size in GB
-n, --name TEXT - Optional name for the volume
-i, --interface [block|file] - Storage interface type (block or file)
--region TEXT - Region to create the volume in
-y, --yes - Skip confirmation prompts
--json - Output JSON for automation
-h, --help - Show this message and exit

flow volume info

Show detailed information about a volume

Usage: flow volume info [OPTIONS] VOLUME_IDENTIFIER

Options:

--json - Output JSON for automation
-d, --details - Also show tasks that reference this volume in their config
--scan-limit INTEGER - Max tasks to scan for --details (default: 200; override via env FLOW_VOLUMES_DETAILS_LIMIT)
--scan-timeout FLOAT - Max seconds to spend scanning for --details (default: 3.0; override via env FLOW_VOLUMES_DETAILS_TIMEOUT)
-h, --help - Show this message and exit

flow volume delete

Delete a volume by ID, name, or 'all'

Usage: flow volume delete [OPTIONS] VOLUME_IDENTIFIER

Options:

-y, --yes - Skip confirmation
--json - Output JSON for automation
-h, --help - Show this message and exit

flow volume delete-all

Delete all volumes (with optional pattern matching)

Usage: flow volume delete-all [OPTIONS]

Options:

-p, --pattern TEXT - Only delete volumes matching pattern
--dry-run - Show what would be deleted
-y, --yes - Skip confirmation
--json - Output JSON for automation
-h, --help - Show this message and exit

flow volume mount

Alias for 'flow mount' – attach a volume to an instance

Usage: flow volume mount [OPTIONS] [VOLUME_IDENTIFIER] [TASK_IDENTIFIER]

Options:

-h, --help - Show this message and exit

flow ssh-key

Manage SSH keys

Usage: flow ssh-key [OPTIONS] COMMAND [ARGS]...

Options:

-v, --verbose - Show detailed SSH key management guide
-h, --help - Show this message and exit

flow ssh-key list

List SSH keys and their state in a simplified, intuitive view

Usage: flow ssh-key list [OPTIONS]

Options:

--show-auto - Show auto-generated keys (hidden by default)
--legend - Show a legend explaining columns and icons
-v, --verbose - Show file paths and detailed information
--json - Output JSON for automation
-h, --help - Show this message and exit

flow ssh-key upload

Upload a specific SSH key to the platform

Usage: flow ssh-key upload [OPTIONS] KEY_PATH

Options:

--name TEXT - Name for the SSH key on platform (skips interactive prompt)
--json - Output JSON for automation
-h, --help - Show this message and exit

flow ssh-key info

Show detailed information about an SSH key

Usage: flow ssh-key info [OPTIONS] KEY_REFERENCE

Options:

-v, --verbose - Show full public key
-h, --help - Show this message and exit

flow ssh-key delete

Delete an SSH key from the platform

Usage: flow ssh-key delete [OPTIONS] KEY_REFERENCE

Options:

-h, --help - Show this message and exit

flow ssh-key require

Mark an SSH key as required (admin only)

Usage: flow ssh-key require [OPTIONS] KEY_REFERENCE

Options:

--unset - Unset required (make key optional)
-h, --help - Show this message and exit

Monitoring

flow pricing

Show market prices and recommendations

Usage: flow pricing [OPTIONS]

Options:

--market - (No-op) Market summary is shown by default
--region TEXT - Filter market by region (e.g., us-central1-b)
--gpu TEXT - Filter to a GPU (e.g., h100, a100)
--gpus INTEGER - Target GPU count for per-instance limit prices
--list - List raw market instances (verbose)
--explain - Explain recommendations (verbose)
--json - Output JSON for automation
-h, --help - Show this message and exit

Utils

flow ssh

SSH to running GPU instances - Interactive shell or remote command execution

Usage: flow ssh [OPTIONS] [INSTANCE_IDENTIFIER] [REMOTE_CMD]...

Options:

--node INTEGER - Node index for multi-instance tasks (remote commands default to all nodes; interactive default is 0)
-v, --verbose - Show detailed help and examples
--json - Output connection parameters as JSON
--fast - Skip readiness wait; prefer cached endpoint and connect immediately
-h, --help - Show this message and exit

Settings

flow theme

Manage CLI color themes (set, get, list)

Usage: flow theme [OPTIONS] COMMAND [ARGS]...

Options:

-h, --help - Show this message and exit

flow theme choose

Interactively choose a theme with live preview

Usage: flow theme choose [OPTIONS]

Options:

-h, --help - Show this message and exit

flow theme clear

Remove persisted theme and return to auto-detect

Usage: flow theme clear [OPTIONS]

Options:

-h, --help - Show this message and exit

flow theme get

Show the currently configured theme

Usage: flow theme get [OPTIONS]

Options:

-h, --help - Show this message and exit

flow theme list

List available themes

Usage: flow theme list [OPTIONS]

Options:

-h, --help - Show this message and exit

flow theme set

Persist a default theme (overrides auto-detect)

Usage: flow theme set [OPTIONS] NAME

Options:

-h, --help - Show this message and exit

flow update

Update Flow to the latest version

Usage: flow update [OPTIONS]

Options:

--check - Check for updates without installing
--force - Force update even if on latest version
--version TEXT - Install specific version
-y, --yes - Skip confirmation prompt
--json - Output in JSON format
--unstable - Include pre-release versions (alpha, beta, rc)
-h, --help - Show this message and exit

Research Mode

flow dev

Persistent dev VM with isolated container environments

Usage: flow dev [OPTIONS] COMMAND [ARGS]...

Options:

-e, --env TEXT - Environment: 'default' (VM) or named (container)
-i, --instance-type TEXT - Instance type for dev VM (e.g., a100, h100). If an existing dev VM has a different instance type, a new dev VM is created instead of reusing
-r, --region TEXT - Preferred region for the dev VM (e.g., us-central1-b)
--image TEXT - Docker image for container execution
-k, --ssh-keys TEXT - Authorized SSH keys (repeatable). Accepts: platform key ID like 'sshkey_ABC123', a local private key path like '~/.ssh/id_ed25519', or a key name like 'id_ed25519'
--force-new - Force creation of new dev VM
-m, --max-price-per-hour FLOAT - Maximum hourly price in USD
--upload / --no-upload - Upload current directory to VM (default: upload)
--upload-path TEXT - Path to upload (default: current directory)
--no-unique - Don't append unique suffix to VM name on conflict
--flat / --nested - Place current dir contents directly into parent (flat). Default uploads into '~/'
-v, --verbose - Show detailed examples and workflows
-h, --help - Show this message and exit

flow dev info

Show dev environment status

Usage: flow dev info [OPTIONS]

Options:

-h, --help - Show this message and exit

flow dev reset

Reset all dev containers

Usage: flow dev reset [OPTIONS]

Options:

-h, --help - Show this message and exit

flow dev stop

Pause the dev VM (preserves boot disk)

Usage: flow dev stop [OPTIONS]

Options:

-h, --help - Show this message and exit

flow submit

Submit a task from YAML configuration

Usage: flow submit [OPTIONS] [CONFIG_FILE] [EXTRA_ARGS]...

Options:

-i, --instance-type TEXT - GPU instance type (e.g., a100, 8xa100, h100)
-r, --region TEXT - Preferred region (e.g., us-west1-b)
-k, --ssh-keys TEXT - Authorized SSH keys (repeatable)
--image TEXT - Docker image to use (default: nvidia/cuda:12.1.0-runtime-ubuntu22.04)
-n, --name TEXT - Task name (default: auto-generated)
--no-unique - Don't append unique suffix to task name
-p, --priority [low|med|high] - Task priority (low/med/high)
--force-new - Force unique task name by appending a suffix
--wait / --no-wait - Wait for task to start running
-d, --dry-run - Validate configuration without submitting
-w, --watch - Watch task progress interactively
--json - Output JSON for automation
--env KEY=VALUE - Environment variables KEY=VALUE (repeatable)
--pricing - Show pricing details in the config table
--slurm - Treat input as a SLURM script
--mount TEXT - Mount storage (format: source or target=source)
--port PORT - Expose a port (repeatable). High ports only (>=1024)
--upload-strategy [auto|embedded|scp|none] - Code upload strategy: auto (default), embedded, scp, or none
--upload-timeout INTEGER - Upload timeout in seconds (default: 600)
--on-upload-failure [continue|fail] - Policy when code upload fails: continue (default) or fail
--upload-code / --no-upload-code - Upload current working directory to the task
-m, --max-price-per-hour FLOAT - Maximum hourly price in USD
-N, --num-instances INTEGER - Number of instances
--distributed [auto|manual] - Distributed rendezvous mode
-v, --verbose - Show detailed configuration guide
-h, --help - Show this message and exit

flow cancel

Cancel GPU tasks - pattern matching uses wildcards by default

Usage: flow cancel [OPTIONS] [TASK_IDENTIFIER]

Options:

-y, --yes - Skip confirmation prompt
--all - Cancel all running tasks
-n, --name-pattern TEXT - Cancel tasks matching wildcard pattern (e.g., 'dev-', '-gpu-8x*', 'train-v?'). Use --regex for regex
--regex - Treat pattern as regex instead of wildcard
-v, --verbose - Show detailed examples and patterns
--interactive / --no-interactive - Force interactive selector on/off regardless of terminal autodetect
-h, --help - Show this message and exit

flow status

List and monitor GPU compute tasks - filter by status, name, or time

Usage: flow status [OPTIONS] [TASK_IDENTIFIER]

Options:

--all - Show all tasks (default: active tasks only)
-s, --state [pending|open|starting|running|paused|preempting|completed|failed|cancelled] - Filter by task status
--limit INTEGER - Maximum number of tasks to show
--force-refresh - Bypass local caches and fetch fresh task data from provider
--json - Output JSON for automation
--since TEXT - Only tasks created since time (e.g., '2h', '2025-08-07T10:00:00Z')
--until TEXT - Only tasks created until time (same formats as --since)
-v, --verbose - Show detailed status information and filtering examples
-w, --watch - Live update the status display
--compact - Compact allocation view
--refresh-rate FLOAT - Refresh rate in seconds for watch mode (default: 3)
--no-origin-group - Disable Flow/Other grouping in main view
-h, --help - Show this message and exit

flow logs

Get logs from a running task

Usage: flow logs [OPTIONS] [TASK_IDENTIFIER]

Options:

-f, --follow - Follow log output
-n, --tail INTEGER - Number of lines to show
--stderr - Show stderr instead of stdout
--source [auto|container|startup|cloud-init|host|both|all] - Log source: 'container' for task logs, 'startup' for startup script, 'cloud-init' for raw cloud-init output, 'host' for system logs, 'both/all' for combined container logs, or 'auto' to pick sensibly
--stream [stdout|stderr|combined] - Which stream to show (overrides --stderr)
--node INTEGER - Specific node (0-indexed) for multi-instance tasks
--since TEXT - Show logs since timestamp (e.g., '5m', '1h', '2024-01-15T10:00:00')
--grep TEXT - Filter lines matching pattern
--no-prefix - Remove node prefix for single-node or piping
--full-prefix - Use full node prefix (e.g., [node-0] instead of [0])
--json - Output JSON for automation
-v, --verbose - Show detailed examples and usage patterns
-h, --help - Show this message and exit

flow upload-code

Upload local code to running tasks - incremental sync via rsync

Usage: flow upload-code [OPTIONS] [TASK_IDENTIFIER]

Options:

-s, --source DIRECTORY - Source directory to upload (default: current directory)
-t, --timeout INTEGER - Upload timeout in seconds (default: 600)
--dest TEXT - Destination directory on the instance. Default is /workspace/ when writable, otherwise ~/{project}
-v, --verbose - Show detailed upload patterns and troubleshooting
--json - Output JSON for automation
--incremental / --full-scan - Use Git to detect changed/untracked files and only upload those (default: full scan). Requires a Git repository
--prepare-absolute - Use sudo -n to prepare absolute destinations (mkdir/chown) when unwritable. Defaults to config/env when omitted
--node INTEGER - Node index for multi-instance tasks (default: 0)
-A, --all-nodes - Upload to all nodes of a multi-instance task
-h, --help - Show this message and exit

flow jupyter

Start Jupyter notebook server on remote task with SSH tunnel

Usage: flow jupyter [OPTIONS] TASK_IDENTIFIER

Options:

--port INTEGER - Local port for SSH tunnel (default: 8888)
--no-open - Don't automatically open browser
--jupyter-port INTEGER - Remote Jupyter port (default: 8888)
-h, --help - Show this message and exit

flow mount

Attach storage volumes to tasks (may require machine restart to take effect)

Usage: flow mount [OPTIONS] [VOLUME_IDENTIFIER] [TASK_IDENTIFIER]

Options:

-v, --volume TEXT - Volume ID or name to mount
-t, --task TEXT - Task ID or name to mount to
-i, --instance INTEGER - Specific instance index (0-based) for multi-instance tasks (not yet supported)
-m, --mount-point TEXT - Custom mount path on the instance (default: /volumes/{volume_name})
--dry-run - Preview the mount operation without executing
-V, --verbose - Show detailed mount workflows and troubleshooting
--wait / --no-wait - Wait for SSH and verify the mount before exiting (default: wait)
--persist - Attempt to persist the mount in /etc/fstab after verification
-y, --yes - Skip confirmation when attaching to a running instance (may pause VM)
--json - Output JSON for automation
-h, --help - Show this message and exit

flow template

Generate editable YAML templates (minimal or full)

Usage: flow template [OPTIONS] COMMAND [ARGS]...

Options:

-h, --help - Show this message and exit

flow template task

Generate a Task YAML template

Usage: flow template task [OPTIONS]

Options:

--full - Generate full, commented template
-o, --output FILE - Write to file
--force - Overwrite existing output file
--name TEXT - Seed task name
--no-unique - Set unique_name: false
-i, --instance TEXT - Seed instance_type (e.g., h100, 8xh100)
--min-gpu-mem INTEGER - Seed min_gpu_memory_gb (mutually exclusive with --instance)
-c, --command TEXT - Seed command (multi-line supported)
--image TEXT - Seed image
--env TEXT - Seed environment variables as KEY=VALUE (repeatable)
--port INTEGER - Seed ports (repeatable, high ports only)
--priority [low|med|high] - Seed priority
--max-price-per-hour FLOAT - Seed max_price_per_hour (USD)
-h, --help - Show this message and exit

Learn

flow ask

Ask questions about the Mithril marketplace

Usage: flow ask [OPTIONS] QUESTION

Options:

--verbose - Show detailed execution information
--json - Output response as JSON
-h, --help - Show this message and exit

flow example

Run ready-to-run starters and view their configurations

Usage: flow example [OPTIONS] [EXAMPLE_NAME]

Options:

--show - Show starter YAML configuration instead of running
-v, --verbose - Show detailed starter descriptions
-y, --yes - Skip confirmation prompt (resource launch)
-h, --help - Show this message and exit

PreviousQuickstart NextSDK research preview

Last updated 1 month ago