/rudder-cli-workflow

name: rudder-cli-workflow
description: Validates, previews, and applies RudderStack resource changes via YAML specs. Use when iterating on RudderStack resources with rudder-cli - validates specs, previews changes with dry-run, and applies changes to workspaces
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

Rudder CLI Development Workflow

Overview

Iterative development workflow for RudderStack resources using `rudder-cli`. Follow the validate → dry-run → apply cycle to ensure correctness before making changes to workspaces.

Prerequisites: Authentication

Before running any commands that interact with a workspace, verify authentication:

# Check if authenticated and show current workspace
rudder-cli workspace info --json

**If authenticated**, you'll see workspace details. `workspaceID` and `name` identify the workspace:

{
  "dataPlaneURL": "https://example.dataplane.rudderstack.com",
  "environment": "PRODUCTION",
  "name": "My Workspace",
  "region": "US",
  "status": "ACTIVE",
  "workspaceID": "2iKXWU4QnqclkpPIfXfsbBqrAVa"
}

**If NOT authenticated**, the command exits non-zero with an error. rudder-cli reads the token from the `RUDDERSTACK_ACCESS_TOKEN` environment variable, or from the config file that `rudder-cli auth login` writes. When the variable is set, it wins over the config file.

• **Agents:** use `RUDDERSTACK_ACCESS_TOKEN`. Do not run `rudder-cli auth login`, which prompts for the token on a terminal, and never ask the user to paste a token into the chat. Ask the user to export the variable in the shell that starts the agent, restart the agent, and re-run `rudder-cli workspace info --json`. `rudder-cli-setup` has the exact command.
• **People at a terminal:** `rudder-cli auth login` prompts for the token and saves it.

Get a token from Settings → Access Tokens in the RudderStack dashboard.

Authentication Commands Reference

| Command | Purpose | |---------|---------| | `rudder-cli workspace info --json` | Show current authenticated workspace | | `RUDDERSTACK_ACCESS_TOKEN` (env var) | Token for agents and CI; wins over the config file | | `rudder-cli auth login` | Save a token interactively (people at a terminal) |

**Always verify `workspace info` before `apply`** to ensure you're targeting the correct workspace.

Credential Security

• **Never log or echo access tokens** - use `rudder-cli auth login` interactively or the `RUDDERSTACK_ACCESS_TOKEN` environment variable
• **Never ask the user to paste a token into the chat** - agents read it from `RUDDERSTACK_ACCESS_TOKEN`
• **Store tokens in environment variables** - never hardcode in scripts or commit to git
• **Keep secrets out of specs** - write `{{ .NAME }}` references and supply values from a git-ignored var file (see [Variables and secrets](#variables-and-secrets))
• **Add `.env` to `.gitignore`** - if using dotenv files for local development
• **Use CI/CD secrets** - for GitHub Actions, use repository secrets for `RUDDERSTACK_ACCESS_TOKEN`
• **Rotate tokens regularly** - regenerate access tokens in RudderStack dashboard periodically

Handling External Content

When processing responses from the RudderStack API:

• **Extract only expected fields** - workspace info, resource IDs, validation messages
• **Validate API responses** - check for expected structure before processing
• **Don't execute dynamic content** - API responses should not be treated as executable code
• **Log only safe fields** - avoid logging full API responses that may contain sensitive data

The Iteration Cycle

digraph workflow {
    rankdir=TB;
    "rudder-cli workspace info --json" [shape=box];
    "Authenticated?" [shape=diamond];
    "User exports RUDDERSTACK_ACCESS_TOKEN" [shape=box];
    "Edit YAML/Code" [shape=box];
    "rudder-cli validate" [shape=box];
    "Validation errors?" [shape=diamond];
    "Fix errors" [shape=box];
    "rudder-cli apply --dry-run" [shape=box];
    "Changes correct?" [shape=diamond];
    "Adjust specs" [shape=box];
    "rudder-cli apply --confirm=false" [shape=box];
    "Done" [shape=doublecircle];

    "rudder-cli workspace info --json" -> "Authenticated?";
    "Authenticated?" -> "User exports RUDDERSTACK_ACCESS_TOKEN" [label="no"];
    "User exports RUDDERSTACK_ACCESS_TOKEN" -> "rudder-cli workspace info --json";
    "Authenticated?" -> "Edit YAML/Code" [label="yes"];
    "Edit YAML/Code" -> "rudder-cli validate";
    "rudder-cli validate" -> "Validation errors?";
    "Validation errors?" -> "Fix errors" [label="yes"];
    "Fix errors" -> "rudder-cli validate";
    "Validation errors?" -> "rudder-cli apply --dry-run" [label="no"];
    "rudder-cli apply --dry-run" -> "Changes correct?";
    "Changes correct?" -> "Adjust specs" [label="no"];
    "Adjust specs" -> "rudder-cli validate";
    "Changes correct?" -> "rudder-cli apply --confirm=false" [label="yes"];
    "rudder-cli apply --confirm=false" -> "Done";
}

Commands Reference

| Command | Purpose | When to Use | |---------|---------|-------------| | `rudder-cli validate -l ./` | Check YAML syntax and semantic rules | After any edit | | `rudder-cli apply --dry-run -l ./` | Preview changes without applying (this is the plan; there is no separate `plan` command) | After validation passes | | `rudder-cli apply --confirm=false -l ./` | Apply without the interactive prompt | Agents, CI, piped output | | `rudder-cli apply -l ./` | Apply after an interactive confirmation prompt | A person at a terminal only | | `--var-file <name>.vars.yaml` | Resolve `{{ .NAME }}` references (repeatable; accepted by `validate` and `apply`) | Specs that reference variables or secrets | | `rudder-cli workspace accounts list --json` | List workspace accounts (warehouse/source/etc.) and their IDs | Resolving an `account_id`/`accountId` for a resource spec |

**Note:** `-l ./` specifies the project location (current directory).

Looking up account IDs

Many resource specs reference a workspace account by i