/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

**If authenticated**, you'll see workspace details:

Workspace Information:
  ID:   2iKXWU4QnqclkpPIfXfsbBqrAVa
  Name: My Workspace

**If NOT authenticated**, you'll see an error. Authenticate first:

rudder-cli auth login

This will prompt for your RudderStack access token. Get one from: Settings → Access Tokens in the RudderStack dashboard.

Authentication Commands Reference

| Command | Purpose | |---------|---------| | `rudder-cli auth login` | Authenticate with access token | | `rudder-cli workspace info` | Show current authenticated workspace |

**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 `RUDDER_ACCESS_TOKEN` environment variable
• **Store tokens in environment variables** - never hardcode in scripts or commit to git
• **Add `.env` to `.gitignore`** - if using dotenv files for local development
• **Use CI/CD secrets** - for GitHub Actions, use repository secrets for `RUDDER_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" [shape=box];
    "Authenticated?" [shape=diamond];
    "rudder-cli auth login" [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" [shape=box];
    "Done" [shape=doublecircle];

    "rudder-cli workspace info" -> "Authenticated?";
    "Authenticated?" -> "rudder-cli auth login" [label="no"];
    "rudder-cli auth login" -> "rudder-cli workspace info";
    "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" [label="yes"];
    "rudder-cli apply" -> "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 | After validation passes | | `rudder-cli apply -l ./` | Apply changes to workspace | After dry-run review | | `rudder-cli apply --confirm=false -l ./` | Apply without the interactive prompt | CI, piped output, agent contexts | | `rudder-cli plan -l ./` | Show detailed execution plan | Alternative to dry-run | | `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 id — e.g. a Data Graph's `spec.account_id` needs the warehouse account it runs against. Resolve it from the CLI rather than guessing:

# Always use --json in agent/non-interactive contexts.
# The plain table output requires a TTY and fails with
# "could not open a new TTY" when piped.
rudder-cli workspace accounts list --json

Each line is one account object. The fields that matter:

• **`id`** — this is the value to paste into `account_id` / `accountId` in a spec.
• **`name`** — human label (e.g. `Snowflake`).
• **`definition.category`** — account role: `wht` = warehouse connection, `source` = source connection, `profilesStore`, etc.
• **`definition.type`** — engine: `snowflake`, `databricks`, `git`, …
• **`options`** — connection details (`account`, `dbname`, `warehouse`, `schema`, `role`, `user`) to disambiguate when several accounts share a name.

Filter to narrow the list:

# RETL source warehouse accounts (what a Data Graph needs)
rudder-cli workspace accounts list --category source --json

# By engine
rudder-cli workspace accounts list --type snowflake --json

**This is the authoritative way to discover account IDs** — including accounts created through the Data Graph UI or a warehouse connection, which are *not* discoverable via `rudder-mcp` (the MCP only surfaces accounts reachable through a rETL source or destination). When working without a rETL source yet (e.g. building a work