---
title: "Use gcx | Grafana Cloud documentation"
description: "Use the gcx command-line tool to pull, edit, validate, push, and run Grafana Workflows, and read the results of workflow runs."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Use gcx

> Note
> 
> Grafana Workflows is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

[gcx](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/) is the Grafana command-line tool. It manages Grafana Workflows the same way it manages other Grafana resources. You can save workflows to files, edit them, check them, and send them back to Grafana. You can also run workflows and read their results.

To have an AI agent run these commands for you, refer to [Build workflows with an AI agent](/docs/grafana-cloud/platform/workflows/as-code/build-with-ai).

## Before you begin

Before you start, make sure you have:

- A Grafana Cloud stack with the Workflows app installed.
- The Editor basic role and edit access to the folder you want to use. For details, refer to [Manage access](/docs/grafana-cloud/platform/workflows/manage-access).
- gcx installed and signed in to your stack. For details, refer to [Install gcx](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/installation/) and [Configure gcx](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/configuration/). To sign in with `gcx login`, you need the gcx User role. Grafana grants it to the Viewer, Editor, and Admin basic roles by default.

The examples on this page use a Bash-compatible shell, such as the terminal on macOS or Linux, or Windows Subsystem for Linux (WSL).

## Find workflows

gcx calls workflow definitions `definitions`. To refer to one workflow, add its ID, for example, `definitions/incident-kickoff`. The ID is the workflow’s `metadata.name`.

To list every workflow you can access, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources get definitions --limit 0
```

The `--limit 0` option turns off the default limit of 50 workflows.

To print one workflow as YAML, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources get definitions/incident-kickoff -o yaml
```

## Save workflows to files

To save your workflows as files, for example, to keep them in Git, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources pull definitions -p ./workflows -o yaml
```

gcx writes one YAML file for each workflow in `./workflows/definitions.v1alpha1.workflows.ext.grafana.app/`. It leaves out fields that Grafana manages, so the files are ready to edit and send back.

## Create or update workflows

To send workflow files to Grafana, follow these steps:

1. Write or edit a workflow file in `./workflows/`.
   
   Each file needs the `grafana.app/folder` annotation. For the file format, refer to [Understand the workflow definition](/docs/grafana-cloud/platform/workflows/as-code/#understand-the-workflow-definition).
2. Check the files without saving anything:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   gcx resources push -p ./workflows --dry-run \
     --assume-server-dry-run definitions.workflows.ext.grafana.app
   ```
   
   The `--assume-server-dry-run` option tells gcx to ask Workflows to check the files without saving them. If Workflows finds a problem, it names it, for example, `step "greet" is missing required field "template" for type "transform"`. Without that option, gcx checks only that each file parses and that your stack supports workflow definitions. It doesn’t check the workflow spec.
3. Send the files:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   gcx resources push -p ./workflows
   ```
   
   gcx creates workflows that don’t exist and updates the ones that do.
4. Confirm the change. Open the Workflows app, go to **Manage workflows**, and find your workflow.

> Note
> 
> gcx skips workflows that Terraform or another tool manages. To include them in `pull` or `push`, add `--include-managed`. When you can, change these workflows with the tool that manages them.

## Edit or delete a workflow

To open a workflow in your text editor, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources edit definitions/incident-kickoff
```

gcx saves your change when you close the editor.

To delete a workflow, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources delete definitions/incident-kickoff
```

## Run workflows and read results

The `gcx api` command sends requests to the Workflows API with your gcx sign-in. The requests use the same endpoints as [Use the API](/docs/grafana-cloud/platform/workflows/as-code/use-the-api).

> Caution
> 
> The Workflows run endpoints might change during public preview.

The endpoints share a long path. To shorten the commands, save the path in a variable:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
export WF_API=/api/plugins/grafana-workflows-app/resources/api/v1
```

### Run a workflow

To run a saved, enabled workflow with test event data, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx api "$WF_API/workflows/incident-kickoff/run" \
  -d '{"inputs": {"data": {"incidentID": "123"}}}'
```

The response includes three IDs: `definition_uid`, `instance_id`, and `execution_id`. You need all three to read the result.

To test a draft that you haven’t saved, use the `trigger` endpoint instead. For details, refer to [Test a draft definition](/docs/grafana-cloud/platform/workflows/as-code/use-the-api/#test-a-draft-definition).

### Read the result of a run

To get a run’s status and the output of each step, run the following command with the three IDs from the run:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx api "$WF_API/runs/<DEFINITION_UID>/<INSTANCE_ID>/<EXECUTION_ID>" \
  --jq '{status, error_message, steps: [.steps[] | {name, status, outputs, error}]}'
```

gcx includes the `--jq` option, so you don’t need to install anything else. The filter in this example prints only the status, any error, and each step’s output.

To find a workflow’s *DEFINITION\_UID*, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx resources get definitions/incident-kickoff --jq .metadata.uid
```

### List failed runs

To list the five most recent failed runs of a workflow, run the following command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
gcx api "$WF_API/runs/<DEFINITION_UID>?status=failed&count=5"
```

For all the filters you can use, refer to [List runs parameters](/docs/grafana-cloud/platform/workflows/reference/api/#list-runs-parameters).

## Next steps

- [Build workflows with an AI agent](/docs/grafana-cloud/platform/workflows/as-code/build-with-ai)
- [Use the API](/docs/grafana-cloud/platform/workflows/as-code/use-the-api)
- [Use Terraform](/docs/grafana-cloud/platform/workflows/as-code/use-terraform)