Rundeck Claude Plugin

This repository contains a local Claude plugin for working with Rundeck and PagerDuty.

The plugin defines three skills:

• rundeck-api — interacts with the Rundeck REST API: importing/exporting jobs, running and monitoring executions, managing webhooks, browsing key storage, discovering installed plugins, and managing runners.
• rundeck-author — designs and writes Rundeck job YAML definitions: job structure, step types, options, variable syntax, conditionals, log filters, and plugin configuration.
• pagerduty — interacts with the PagerDuty REST API: managing incidents, users, escalation policies, on-call schedules, services, incident workflows, and more.

Required Environment Variables

The skill requires these environment variables to be set before Claude uses the plugin:

• RD_URL - base URL for your Rundeck server
• RD_TOKEN - for access to Rundeck REST API
• PD_API_TOKEN - for access to PagerDuty REST API

RD_PROJECT is optional — if not set, Claude will ask you which project to use or list available projects.

RD_URL

This is the base URL of your Rundeck server.

Example:

export RD_URL="https://rundeck.example.com"

How to get it:

• use the URL you already open in the Rundeck web UI
• ask your Rundeck administrator for the correct server URL

RD_TOKEN

This is a Rundeck API token with permission to read or manage the resources you want Claude to use.

Example:

export RD_TOKEN="your-api-token"

How to get it:

• in Rundeck, create or copy an API token from your user profile or token management area
• if token creation is restricted, ask your Rundeck administrator to provide one with the needed permissions

Do not commit this value to the repository.

RD_PROJECT (optional)

If set, this is the Rundeck project Claude will use by default.

Example:

export RD_PROJECT="my-project"

If not set, Claude will ask or list available projects when a project is needed.

PD_API_TOKEN (optional)

If set, enables PagerDuty integration — Claude can look up on-call schedules, incidents, and services alongside Rundeck operations.

Example:

export PD_API_TOKEN="your-pagerduty-api-token"

How to get it:

• in PagerDuty, generate a personal API token from My Profile > User Settings > Create API User Token
• personal/user tokens are preferred over global API tokens

Do not commit this value to the repository.

Example Shell Setup

You can export the required variables in your current shell session:

export RD_URL="https://rundeck.example.com"
export RD_TOKEN="your-rundeck-api-token"
export RD_PROJECT="my-project"  # optional
export PD_API_TOKEN="your-pagerduty-api-token"

If you want them to persist, add the exports to your shell profile such as ~/.zshrc or ~/.bashrc.

Alternative: .env file

If a variable isn't already exported in the shell, both rd-api and pd-api fall back to loading it from a .env file (KEY=value per line, # comments allowed), searched starting at the current directory and walking up. Real environment variables always take precedence over .env values. Never commit a .env file with real credentials — add it to .gitignore.

Installing via the Plugin Marketplace

This repo is itself a marketplace (.claude-plugin/marketplace.json) containing one plugin (rundeck). To install it:

claude plugin marketplace add https://github.com/martindstone/rundeck-claude-plugin
claude plugin install rundeck@rundeck-claude-plugin

No need to clone first — marketplace add accepts the GitHub URL directly. A local path (e.g. /path/where/you/cloned/rundeck-claude-plugin) also works if you already have a clone.

Before running Claude, make sure RD_URL, RD_TOKEN and PD_API_TOKEN are set in the shell where you launch Claude (see Required Environment Variables above).

Testing the Plugin Locally (development)

For iterating on the skills themselves, skip the marketplace and point Claude directly at the repository directory with --plugin-dir — changes to the SKILL.md files take effect immediately without reinstalling.

claude --plugin-dir /path/where/you/cloned/rundeck-claude-plugin

Before running Claude, make sure RD_URL, RD_TOKEN and PD_API_TOKEN are set in the shell where you launch Claude.

Once Claude starts with the plugin loaded, you can try prompts like:

• "Create a Rundeck job that takes a pagerduty incident ID as a parameter and checks disk usage on all nodes and puts the result on the incident as a note. make it available from pagerduty as an incident workflow that posts to a rundeck webhook listener"
• "List jobs in my Rundeck project"
• "Who is on call for service X"
• "How many incidents were there in service X this week"

You can tell claude your PagerDuty service, Rundeck project, etc., by adding notes to CLAUDE.md in your project.

Notes

The skills are written to prefer safe behavior:

• they require the Rundeck and PagerDuty environment variables to be set
• API tokens are never echoed to the terminal
• confirmation is required before creating, updating, or deleting any resource in Rundeck or PagerDuty
• rundeck-api and rundeck-author work together: rundeck-author generates job YAML, then rundeck-api imports and runs it
• job YAML is shown to the user before being imported or executed