Command Line Interface for the YellowDog Platform

Overview

This is a set of Python CLI commands for interacting with the YellowDog Platform, also providing examples of usage of the YellowDog Python SDK.

The CLI is one command, yd. Most of what it does names the object acted on, then what to do to it — yd workrequirement submit, yd instance terminate — and yd <noun> --help lists a noun's verbs; yd help lists everything. The commands support:

• Work Requirements — submitting, cancelling, holding, starting, finishing and reprioritising them, and comparing them against Worker Pools, with yd workrequirement (short form yd wr)
• Task Groups and Tasks — reprioritising Task Groups and comparing them against Worker Pools with yd taskgroup (yd tg), and cancelling or aborting Tasks with yd task
• Worker Pools — provisioning, resizing and shutting them down, and refreshing or regenerating Configured Worker Pools' tokens, with yd workerpool (yd wp)
• Compute Requirements — instantiating, resizing, stopping, starting, reprovisioning, terminating and setting when they are automatically terminated with yd computerequirement (yd cr)
• Instances and Nodes — stopping, starting, restarting, deprovisioning and terminating individual Instances with yd instance, and Worker Pool Nodes' Instances with yd node, which also shuts Nodes down and submits Node Actions to them; listing and showing Workers with yd worker
• Resources — creating, updating and removing Compute Source Templates, Compute Requirement Templates, Keyrings, Credentials, Image Families, Namespaces, Allowances, Configured Worker Pools, Attribute Definitions, Namespace Policies, Groups, Applications and Users (update only) with yd resource, from specification files or on the command line, and showing or removing them by name
• Allowances — boosting them with yd allowance
• Remote data stores — uploading, downloading, listing, deleting and copying files with yd data
• Cloud provider setup (AWS, Azure, GCP) with the yd cloudwizard command
• Cloud regions, instance types and prices, as the YellowDog Platform knows them, with yd cloudinfo
• Inspecting — listing items with yd list, showing one in full with yd show, following event streams with yd follow, and waiting for Work Requirements, Worker Pools or Compute Requirements to finish with yd wait. Each Platform noun has list and show verbs of its own, such as yd task list --within my-work-requirement --status failed.
• Showing the details of the current Application with the yd application command
• Diagnosing the configuration, credentials and connectivity with the yd doctor command
• Reporting the processed values of variable substitutions with the yd variables command
• Completing commands, verbs, options and their values on Tab, in bash, zsh, fish and PowerShell, with the yd completion command

The yd-* commands, such as yd-submit and yd-list, are deprecated: they still run, with a warning, until a future release; yd help --deprecated says what replaces each.

Utility commands are also provided: yd init (a starter configuration file), yd format-json, yd help, yd jsonnet2json, yd schema, and yd version. For a full list of commands run yd help.

The remote data store commands — the yd data verbs upload, download, delete, list and copy — use rclone, and do not require YellowDog credentials. An rclone binary already on your PATH is used in preference, and is never modified. Otherwise one is downloaded to a per-user cache directory the first time it's needed.

Installation

Python 3.10 or later is required. Choose the installation that fits how you work; uv supplies Python itself if you have none.

uv tool — the commands on your PATH everywhere, with no environment to activate:

uv tool install yellowdog-cli

A virtual environment created with uv, downloading Python 3.14 if it is not installed:

uv venv --python 3.14 yd-env
source yd-env/bin/activate   # macOS / Linux; on Windows: yd-env\Scripts\activate
uv pip install yellowdog-cli

pip in a virtual environment, with a Python you have installed:

python3 -m venv yd-env
source yd-env/bin/activate   # macOS / Linux; on Windows: yd-env\Scripts\activate
pip install -U yellowdog-cli

Other installers, such as pipx, work too.

Optional Extras

Four optional extras are available:

List the ones you need in square brackets at installation time, e.g. to install all four:

uv tool install "yellowdog-cli[jsonnet,commander,cloudwizard,mcp]"    # uv tool
uv pip install -U "yellowdog-cli[jsonnet,commander,cloudwizard,mcp]"  # uv virtual environment
pip install -U "yellowdog-cli[jsonnet,commander,cloudwizard,mcp]"     # pip

Commander GUI

yd commander is an optional cross-platform desktop GUI for driving the CLI, installed via the commander extra above:

pip install -U "yellowdog-cli[commander]"
yd commander

It works by running yd commands on your behalf and displaying their output. See the Commander documentation for details.

MCP Server

yd mcp is an optional MCP server exposing the yd commands as tools for an agent, installed via the mcp extra above:

pip install -U "yellowdog-cli[mcp]"
yd mcp config.toml

It runs yd commands on an agent's behalf, with --json, and returns their results. See the MCP server documentation for details.

Documentation

For a first run from start to finish, follow the CLI track of Getting Started in the YellowDog Documentation.

The CLI's own documentation is in the GitHub repository, one page per topic, mapped in its README's Documentation section: guides to configuration, variable substitutions, Work Requirements, Worker Pools, the data client, resources, Jsonnet and checking specifications, and reference pages for the commands (the Command List), the Work Requirement properties and the --json output and exit codes. Help is also available for every command with --help or -h.

This documentation should be read in conjunction with the main YellowDog Documentation.