Documentation Grafana Cloud Platform Workflows Manage as code Use gcx

Use gcx

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.

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.
• gcx installed and signed in to your stack. For details, refer to Install gcx and Configure gcx. 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

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

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

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.

2. Check the files without saving anything:

   Bash Copy

   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

   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.

Edit or delete a workflow

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

Bash Copy

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

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.

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

Bash Copy

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

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.

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

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

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

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

For all the filters you can use, refer to List runs parameters.

Next steps

• Build workflows with an AI agent
• Use the API
• Use Terraform