# Source: https://docs.warp.dev/terminal/entry/yaml-workflows.md

# YAML Workflows

{% hint style="danger" %}
You can continue to use YAML-based workflows, but we recommend using new [workflows in Warp Drive](https://docs.warp.dev/knowledge-and-collaboration/warp-drive/workflows) instead for a better editing experience.
{% endhint %}

## What is it

Workflows are easily parameterized and searchable by name, description, or command arguments. [Common Workflows](https://github.com/warpdotdev/workflows) sourced by the Warp team and community are readily available within the app. Additionally, you can create and scope Workflows locally or to a git repository.

## How to use it

* Open the [Command Search](https://docs.warp.dev/terminal/entry/command-search) or Workflow Search `CTRL-SHIFT-R` panel to find Workflows.
* Once inside the menu, start typing in the search bar to filter the existing Workflows. (e.g. git, android, npm, etc.)
* When a Workflow is selected with `ENTER`, you can use `SHIFT-TAB` to cycle through the arguments.
* You can also expand the menu horizontally with the mouse by dragging it on the right edge.

{% hint style="info" %}
Tailor your [Command Search](https://docs.warp.dev/terminal/entry/command-search) experience by toggling off "Show Global Workflows" in `Settings > Features`. When disabled, your search will exclusively encompass YAML and Warp Drive Workflows.
{% endhint %}

## How it works

<figure><img src="https://4009768362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPsjNxoJ0NFCXW6rRdHH3%2Fuploads%2Fgit-blob-e4870de99dab35a374dd44479208db26bf03e0b3%2Fyaml_workflows_demo.gif?alt=media" alt="YAML Workflows Demo"><figcaption><p>YAML Workflows Demo</p></figcaption></figure>

### How is this Different from Aliases?

Workflows solve some major pain points with aliases, specifically the:

1. need to context switch
   1. leave vim, source dotfiles, or reset shell
2. difficulty with attaching documentation
3. inability to easily search or share
4. inability to easily parameterize

## Creating Custom Workflows

### How to create a workflow with YAML

You can store local workflows (scoped to your machine) in:

{% tabs %}
{% tab title="macOS" %}

```bash
$HOME/.warp/workflows/
```

{% endtab %}

{% tab title="Windows" %}

```powershell
$env:APPDATA\warp\Warp\data\workflows\
```

{% endtab %}

{% tab title="Linux" %}

```bash
${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/
```

{% endtab %}
{% endtabs %}

Or, you can share them with your team by saving them in `{{path_to_git_repo}}/.warp/workflows/`. Local and repository Workflows can be accessed under the "My Workflows" and "Repository Workflows" tab of the Workflows menu, respectively.

See the existing Workflow spec within the [Workflows repo](https://github.com/warpdotdev/Workflows/tree/main/specs) for examples. Additionally, we outline the file format below:

<details>

<summary><a href="https://github.com/warpdotdev/Workflows/blob/main/FORMAT.md">Workflow File Format</a></summary>

The Workflow file format is a [yaml](https://yaml.org/) file and must have either a \`.yml \` or \`yaml\` extension. If you're new to YAML and want to learn more, see [Learn YAML in Y minutes](https://learnxinyminutes.com/docs/yaml/).

***

**`name`**

The name of the Workflow. Required.

**`command`**

The command that is executed when the Workflow is selected. Required.

**`tags`**

An array of tags that are useful to categorize the Workflow. Optional.

```yaml
tags: ["git", "GitHub"]
```

**`description`**

The description of the Workflow and what it does. Optional.

**`source_url`**

The URL from where the Workflow was originally generated from. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.

**`author`**

The original author of the Workflow. For example, if this Workflow was generated from StackOverflow, the `author` would be the `author` of the StackOverflow post. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.

**`author_url`**

The URL of original author of the Workflow. For example, if this Workflow was generated from StackOverflow, the `author_url` would be the StackOverflow author's profile page. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.

**`shells`**

The list of shells where this Workflow is valid. If not specified, the Workflow is assumed to be valid in all shells. This must be one of `zsh`, `bash`, or `fish`.

**`arguments`**

A Workflow can have parameterized arguments to specify pieces of the Workflow that need to be filled in by the user.

You can specify which part of the Workflow command maps to an argument by surrounding it with two curly braces (`{{<argument>}}`).

For example the Workflow command:

```bash
for {{variable}} in {{sequence}}; do
  {{command}}
done
```

Includes 3 arguments: `variable`, `sequence`, and `command`.

**`arguments.name`**

The name of the argument. The argument name is used within the command to specify the ranges of the argument. Required.

```yaml
name: Example Workflow
command: echo {{string}}
arguments:
  - name: string
    description: The value to echo
```

**`arguments.description`**

The description of the argument. This is surfaced in both [commands.dev](https://www.commands.dev/) and Warp to help users fill in Workflow arguments. Optional

**`arguments.default_value`**

The default value for the argument. If specified, the `default_value` replaces the argument name within the command. Optional

***

</details>

### Where to save workflows

Local Workflows are scoped to your machine. Repository Workflows are scoped to a git repository and can be accessed by anyone who has cloned the repo. *Note:* Repository Workflows will not appear if you are ssh into a remote machine.

{% tabs %}
{% tab title="macOS" %}

```bash
# Local Workflow Path
$HOME/.warp/workflows/

# Repository Workflow Path
{{path_to_git_repo}}/.warp/workflows
```

{% endtab %}

{% tab title="Windows" %}

```powershell
# Local Workflow Path
$env:APPDATA\warp\Warp\data\workflows\

# Repository Workflow Path
{{path_to_git_repo}}\.warp\workflows
```

{% endtab %}

{% tab title="Linux" %}

```bash
# Local Workflow Path
${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/

# Repository Workflow Path
{{path_to_git_repo}}/.warp/workflows
```

{% endtab %}
{% endtabs %}

#### Local Workflows

To start, create a Workflow subdirectory within

{% tabs %}
{% tab title="macOS" %}

```bash
mkdir -p $HOME/.warp/workflows/
```

{% endtab %}

{% tab title="Windows" %}

```powershell
New-Item -Path "$env:APPDATA\warp\Warp\data\workflows\" -ItemType Directory
```

{% endtab %}

{% tab title="Linux" %}

```bash
mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/
```

{% endtab %}
{% endtabs %}

Add your Workflow’s `.yaml` file to this directory; if the file format is valid Warp should automatically load it into the Workflows menu.

`cp ~/path/to/my_awesome_workflow.yaml {{path_to_local_workflow_folder}}`

#### Repository Workflows

You can add a repository Workflow similarly to how you added a local Workflow. Create a Workflows folder in a repository’s root directory and save your `.yaml` file like so:

```
cd {{repository_path}}
mkdir -p .warp/workflows/
cp ~/path/to/my_awesome_workflow.yaml {{path_to_local_workflow_folder}}
```

#### Global Workflows

You can contribute Workflows that will be made available to other Warp users by forking the [Workflows repo](https://github.com/warpdotdev/workflows/tree/main/specs) and opening a pull request. See the [Contributing](https://github.com/warpdotdev/workflows#contributing) section for more details.