sfdx-hardis with AI Coding Agents

sfdx-hardis is built to work with AI coding agents such as Claude Code, GitHub Copilot, Gemini CLI, Cursor, OpenAI Codex, and any other agent that can run shell commands and understands skills.

Over 170 commands expose an --agent flag that switches to a fully non-interactive, automation-safe execution mode: no prompts, no blocking, predictable outputs.

Why sfdx-hardis + AI Agents?

Salesforce DevOps involves many repetitive, multi-step operations: creating feature branches, cleaning metadata, deploying sources, diagnosing orgs, managing users and licenses... These tasks are ideal for AI agents:

• Save tokens and time: agents read clean terminal output instead of navigating verbose interactive UIs.
• Zero prompt interruptions: the --agent flag disables every interactive prompt, applying sensible defaults.
• Fail fast: if a required parameter is missing, the command exits immediately with a descriptive error listing available options.
• Composable: commands can be chained as agent tool calls or shell scripts.
• Works everywhere: any agent that understands skills and can run shell commands can drive sfdx-hardis: Claude Code, Copilot, Gemini, Cursor, Codex, or your own automation.
• Answers about your orgs: a monitoring repository explains itself to agents, so they can answer what changed in an org, when, and through which Pull Request. See below.

The --agent Flag

Add --agent to any supported command to enable non-interactive mode:

# Create a new User Story branch without any prompts
sf hardis:work:new --agent --task-name "PROJ-123 Add account scoring" --target-branch integration --branch-prefix feature

# Run a full org health check
sf hardis:org:monitor:all --agent --target-org myorg@example.com

# Diagnose unused users
sf hardis:org:diagnose:unusedusers --agent --days 180 --target-org myorg@example.com

In agent mode:

• All interactive prompts() calls are disabled.
• Required inputs must be provided as CLI flags: the command fails with a clear error if they are missing.
• Optional inputs apply sensible defaults (documented per command).

Quick Start: Register sfdx-hardis as Agent Skills

All major coding agents support skills, markdown files that describe how to perform a task. Create skill files in your project and the agent will know how to drive sfdx-hardis.

<skills-folder>/new-user-story/SKILL.md

---
name: new-user-story
description: Start a new Salesforce User Story by creating a feature branch. Use when the user wants to start working on a new feature, bug fix, or task.
---

# New Salesforce User Story

When the user asks to start a new Salesforce User Story, run:

sf hardis:work:new --agent --task-name "<TICKET-ID> <description>" --target-branch <branch> --branch-prefix <feature|fix|retrofit>

- Replace <TICKET-ID> and <description> with values from the user's request.
- Check config/.sfdx-hardis.yml for available target branches (usually `integration`).
- Do not pass --open-org unless explicitly asked.

<skills-folder>/save-work/SKILL.md

---
name: save-work
description: Save and push Salesforce work by cleaning sources, updating package.xml, committing, and pushing. Use when the user asks to save, publish, or push their Salesforce changes.
---

# Save Salesforce User Story

When the user asks to save or publish their Salesforce work:

1. Remind the user to stage and commit their pending metadata changes with git.
2. Run: sf hardis:work:save --agent

This will clean sources, update package.xml, and push to the remote.
If the target branch cannot be auto-resolved, add --targetbranch <branch>.

Each skill is a folder holding a SKILL.md file, whose name and description tell the agent when to use it. The skills folder depends on your agent:

GitHub Copilot also reads .claude/skills/ and .agents/skills/, so one folder can serve several agents.

See Using AI Coding Agents for more detailed skill examples: deployment simulation, package configuration, and deployment actions (create, read the status in each org, try in a developer org, retry or close a failed one).

Docker Images with Agent CLIs Pre-installed

For CI/CD pipelines that need to run sfdx-hardis and an AI agent CLI in the same container:

# GitHub Actions, Azure Pipelines
container: ghcr.io/hardisgroupcom/sfdx-hardis-ubuntu-with-agents:latest

# Bitbucket Pipelines
image: ghcr.io/hardisgroupcom/sfdx-hardis-ubuntu-with-agents:latest

# GitLab CI
image: ghcr.io/hardisgroupcom/sfdx-hardis-with-agents:latest

These images include Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, and Cursor pre-installed.

See Installation for all available image variants.

Ask Questions About Your Org History and Deployments

A monitoring repository holds a nightly backup of each org, one commit per day with changes. At each backup, sfdx-hardis writes an AGENTS.md file at its root, with a CLAUDE.md pointing to it. It explains to the agent how the monitoring works, what each file holds, what the backup skips, and how to read the git history. There are no skills to install: open the monitoring repository with your agent and ask.

• "What changed in production last week?"
• "When was the Check_VAT validation rule last modified, and what changed?"
• "Write the report of the changes between March 1 and March 31." The agent writes a markdown file grouping the Added, Removed and Updated components by metadata type
• "Which monitoring checks run on this org, and on which day?"

Set deploymentRepository in the .sfdx-hardis.yml of the monitoring branch to the address of your sfdx-hardis CI/CD repository, and the agent also searches it. It clones it next to the monitoring repository, read-only, finds the branch that deploys to the org, and reads the Pull Requests and the pipeline logs of both repositories with gh, glab, az or the Bitbucket API:

• "Was this Flow change deployed by the pipeline, or made directly in production?"
• "Which Pull Request brought this Apex class to production, and when?"
• "Why did last night's deployment to UAT fail?"
• "Why did last night's backup fail?"

Set grafanaUrl too, and the agent also queries the logs and metrics the monitoring sends to Grafana, through the Grafana API: "How did the API requests limit evolve this quarter?", "On which days did Apex errors spike?".

The agent uses a git provider CLI you are already logged in with, or tokens from a .env file (a read-only GRAFANA_API_TOKEN for Grafana). It only reads: it never pushes, comments, starts a pipeline or changes Grafana. See Ask questions with a coding agent.

All Agent-Ready Commands

The table below lists every sfdx-hardis command that supports --agent. Click the command name to open its full reference page.

Devops

Monitoring

Documentation

Org Utils

Metadata Utils

Package

Command	What an agent can do
hardiscreate	Scaffold a new Salesforce package definition
hardisinstall	Install a managed or unlocked package by its 04t ID
hardismergexml	Merge multiple package.xml files into one
hardisversion:create	Build a new immutable package version
hardisversion:list	List all available versions of a package with their IDs and status
hardisversion:promote	Promote a package version to released status for production installation

Miscellaneous

Command	What an agent can do
hardis:auth:login	Log in to a Salesforce org interactively or via JWT / connected-app OAuth
hardis:cache:clear	Clear the sfdx-hardis local cache (useful when encountering stale metadata or config data)
hardis:config:get	Read and display the merged project / branch / user configuration for the current project
hardis:doctor	Gather local install info and print a ready-to-paste report plus a pre-filled GitHub issue URL
hardis:git:pull-requests:extract	Extract Pull Request data from GitHub, GitLab, or Azure DevOps for reporting and auditing
hardis:mdapi:deploy	Deploy a Metadata API format directory or zip to a Salesforce org
hardis:mdapi:read	Read complete metadata files with the CRUD-based Metadata API, for types a file-based retrieve returns incomplete (Profile, Permission Set)
hardis:mdapi:upsert	Push local source files whole with the CRUD-based Metadata API, the mirror of hardis:mdapi:read
hardis:misc:custom-label-translations	Isolate and export specific custom label translations
hardis:misc:servicenow-report	Retrieve Salesforce user stories and enrich them with ServiceNow data
hardis:misc:toml2csv	Convert TOML structured data files to CSV format for reporting
hardis:org:connect	Authenticate to an existing Salesforce org and register it in the local project config
hardis:org:configure:generic-prompt	Deploy the SfdxHardisGenericPrompt prompt template to the org given by --target-org
hardis:org:create	Provision a new sandbox with the automated setup steps defined in project config
hardis:org:retrieve:sources:dx	Retrieve metadata from an org in SFDX source format
hardis:org:retrieve:sources:dx2	Pull metadata from any org with fine-grained control via package.xml
hardis:org:retrieve:sources:metadata	Retrieve metadata using Metadata API format into the local project
hardis:org:retrieve:sources:retrofit	Retrofit an existing org into an SFDX project by retrieving all current metadata
hardis:project:deploy:notify	Send deployment or simulation status notifications to configured team channels
hardis:project:deploy:quick	Quickly deploy a previously validated set of changes
hardis:project:deploy:simulate	Dry-run a deployment to check what would be deployed without touching the org
hardis:project:deploy:sources:metadata	Deploy sources in Metadata API format to a target org
hardis:project:deploy:start	Run a full deployment pipeline (sfdx-hardis wrapper for sf project deploy start) with error tips
hardis:project:deploy:validate	Check-only validate a deployment without applying changes to the org
hardis:project:generate:gitdelta	Generate a package.xml delta from git history using sfdx-git-delta
hardis:project:skills:import	Import AI coding agent skill configurations from a remote repository into .claude/
hardis:scratch:create	Provision a complete scratch org including package installation, metadata deployment, and data initialization
hardis:scratch:delete	Delete one or more scratch orgs to free up limits
hardis:scratch:pool:localauth	Authenticate locally to a scratch org fetched from the pool
hardis:scratch:pool:refresh	Rebuild and replenish all scratch orgs in the configured pool
hardis:scratch:pool:reset	Empty and reinitialize the scratch org pool (full rebuild)
hardis:scratch:pool:view	Display pool status: capacity, available, expired, and in-use orgs
hardis:source:deploy	Deploy local SFDX project sources to a Salesforce org
hardisget	Fetch one JIRA, Azure Boards or ServiceNow ticket in full, as JSON and optionally as a markdown extract, before implementing it
hardis:source:push	Push local SFDX sources to a scratch org
hardis:source:retrieve	Retrieve metadata from an org and update local SFDX sources

See Also

• Using AI Coding Agents (Detailed Guide): step-by-step skills for Claude Code, Copilot, and other agents
• Coding Agent Auto-Fix: auto-fix deployment errors with AI agents
• AI Setup: configure LLM providers (Claude, OpenAI, Gemini, Ollama) for sfdx-hardis AI features
• Deployment Agent: AI-assisted deployment error resolution

Comments