Metadata-Version: 2.4
Name: yellowdog-cli
Version: 15.7.0
Summary: Python-based CLI for the YellowDog Platform
Author-email: YellowDog Limited <support@yellowdog.co>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yellowdog/yellowdog-cli
Project-URL: Changelog, https://github.com/yellowdog/yellowdog-cli/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyPAC>=0.16.4
Requires-Dist: dateparser
Requires-Dist: fastjsonschema
Requires-Dist: python-dotenv
Requires-Dist: requests
Requires-Dist: rclone-api>=1.5.6
Requires-Dist: rich>=13.9.4
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tomli>=2.4.1
Requires-Dist: yellowdog-sdk>=15.9.1
Provides-Extra: jsonnet
Requires-Dist: jsonnet; extra == "jsonnet"
Provides-Extra: commander
Requires-Dist: PyQt6; extra == "commander"
Provides-Extra: mcp
Requires-Dist: mcp>=2.2; extra == "mcp"
Provides-Extra: cloudwizard
Requires-Dist: boto3; extra == "cloudwizard"
Requires-Dist: botocore; extra == "cloudwizard"
Requires-Dist: google-cloud-compute; extra == "cloudwizard"
Requires-Dist: google-cloud-storage; extra == "cloudwizard"
Requires-Dist: azure-identity; extra == "cloudwizard"
Requires-Dist: azure-mgmt-resource; extra == "cloudwizard"
Requires-Dist: azure-mgmt-network; extra == "cloudwizard"
Requires-Dist: azure-mgmt-storage; extra == "cloudwizard"
Requires-Dist: azure-mgmt-subscription; extra == "cloudwizard"
Provides-Extra: dev
Requires-Dist: cli-test-helpers; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest<9.2; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: python-dispatch; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: tox; extra == "dev"
Requires-Dist: tox-uv; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Command Line Interface for the YellowDog Platform

[![PyPI version](https://img.shields.io/pypi/v/yellowdog-cli)](https://pypi.org/project/yellowdog-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/yellowdog-cli)](https://pypi.org/project/yellowdog-cli/)
[![Licence](https://img.shields.io/pypi/l/yellowdog-cli)](https://github.com/yellowdog/yellowdog-cli/blob/main/LICENSE)

## 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](https://docs.yellowdog.ai/sdk/python/index.html).

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](https://rclone.org)**, 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](https://docs.astral.sh/uv/)** supplies Python itself if you have none.

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

```shell
uv tool install yellowdog-cli
```

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

```shell
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:

```shell
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:

| Extra         | Provides                                                         |
|---------------|------------------------------------------------------------------|
| `jsonnet`     | Jsonnet in place of JSON, for any specification file             |
| `commander`   | The `yd commander` desktop GUI, described below                  |
| `cloudwizard` | The cloud provider SDKs required by the `yd cloudwizard` command |
| `mcp`         | The `yd mcp` MCP server, described below                         |

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

```shell
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:

```shell
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](https://github.com/yellowdog/yellowdog-cli/blob/main/yellowdog_cli/commander/README.md) 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:

```shell
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](https://github.com/yellowdog/yellowdog-cli/blob/main/yellowdog_cli/mcp/README.md) for details.

## Documentation

For a first run from start to finish, follow the CLI track of **[Getting Started](https://docs.yellowdog.ai/#/getting-started/getting-started)** in the YellowDog Documentation.

The CLI's own documentation is in the [GitHub repository](https://github.com/yellowdog/yellowdog-cli), one page per topic, mapped in its README's **[Documentation](https://github.com/yellowdog/yellowdog-cli/blob/main/README.md#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](https://github.com/yellowdog/yellowdog-cli/blob/main/docs/commands.md)**), 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](https://docs.yellowdog.ai)**.
