sfdx-hardis with AI Coding Agents

sfdx-hardis is built to work seamlessly 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 130 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.

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

# 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.md

# 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>

- 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.md

# 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>.

The skills folder depends on your agent:

Agent	Skills folder
Claude Code	`.claude/skills/`
GitHub Copilot	`.github/copilot/`
Gemini CLI	`.gemini/skills/`
Cursor	`.cursor/skills/`
OpenAI Codex	`.codex/skills/`

See Using AI Coding Agents for more detailed skill examples including org diagnostics.

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
image: hardisgroupcom/sfdx-hardis-ubuntu-with-agents:latest

# GitLab CI
image: 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.

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.

Authentication & Org Setup

Command	What an agent can do
hardis:auth:login	Log in to a Salesforce org interactively or via JWT / connected-app OAuth
hardis:org:connect	Authenticate to an existing Salesforce org and register it in the local project config
hardis:org:create	Provision a new sandbox with the automated setup steps defined in project config

Development Workflow

Command	What an agent can do
hardis:work:new	Create a new User Story Git branch and optionally provision a scratch org or sandbox - required flags: `--task-name`, `--target-branch`
hardis:work:save	Clean metadata, update `package.xml` / `destructiveChanges.xml`, commit, and push - optional: `--targetbranch`, `--noclean`, `--nogit`
hardis:work:refresh	Pull latest changes from target branch, merge, and push to the current scratch org or sandbox
hardis:work:resetselection	Soft-reset staged commits to re-evaluate which changes go into the merge request
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:pull	Pull the latest metadata changes from a scratch org into the local SFDX project
hardis:scratch:push	Push local SFDX project metadata to the scratch org
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:project:create	Scaffold a new SFDX project with sfdx-hardis configuration
hardis:project:skills:import	Import AI coding agent skill configurations from a remote repository into `.claude/`
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

Source Retrieval & Deployment

Command	What an agent can do
hardis:project:deploy:smart	Smart-deploy SFDX sources with delta, dependency resolution, and pre/post hooks
hardis:project:deploy:simulate	Dry-run a deployment to check what would be deployed without touching the 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:deploy:quick	Quickly deploy a previously validated set of changes
hardis:project:deploy:notify	Send deployment or simulation status notifications to configured team channels
hardis:project:deploy:sources:metadata	Deploy sources in Metadata API format to a target org
hardis:project:generate:gitdelta	Generate a `package.xml` delta from git history using sfdx-git-delta
hardis:project:generate:flow-git-diff	Generate a visual Flow diff markdown between two commits for deployment review
hardis:project:generate:bypass	Generate bypass custom permissions and fields for automations on selected sObjects
hardis:project:metadata:activate-decomposed	Activate decomposed metadata support for all supported types in the project
hardis:org:retrieve:packageconfig	Retrieve installed packages from an org and optionally update project config - flags: `--packages`, `--update-existing-config`, `--update-all-config`
hardis:org:retrieve:sources:analytics	Retrieve the full CRM Analytics configuration from an org
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:mdapi:deploy	Deploy a Metadata API format directory or zip to a Salesforce org
hardis:source:deploy	Deploy local SFDX project sources to a Salesforce org
hardis:source:push	Push local SFDX sources to a scratch org
hardis:source:retrieve	Retrieve metadata from an org and update local SFDX sources

Org Diagnostics

Command	What an agent can do
hardis:org:diagnose:unusedusers	List users who have not logged in for N days - flag: `--days` (default 180)
hardis:org:diagnose:unusedlicenses	Identify Permission Set License Assignments no longer linked to an active Permission Set
hardis:org:diagnose:licenses	Full overview of Salesforce license consumption
hardis:org:diagnose:legacyapi	Detect calls to retired or soon-to-be-retired API versions
hardis:org:diagnose:apex-api-version	Find Apex classes deployed with API versions below a configurable threshold
hardis:org:diagnose:audittrail	Export Setup Audit Trail to CSV, highlighting suspect admin actions
hardis:org:diagnose:deployments	Query DeployRequest records to analyze recent deployments and validations
hardis:org:diagnose:flex-queue	Count `AsyncApexJob` records in the Apex flex queue (status = Holding)
hardis:org:diagnose:instanceupgrade	Show the scheduled date of the next Salesforce major release for the org's instance
hardis:org:diagnose:releaseupdates	Export Release Updates to CSV and flag those requiring action
hardis:org:diagnose:storage-stats	Analyze data storage consumption by object with flexible grouping
hardis:org:diagnose:minimalpermsets	Find permission sets with very few permissions (possible candidates for cleanup)
hardis:org:diagnose:underusedpermsets	Identify permission sets and groups that are rarely assigned
hardis:org:diagnose:unsecure-connected-apps	Find Connected Apps with insecure OAuth settings
hardis:org:diagnose:unused-apex-classes	List async Apex classes (Batch/Queueable/Schedulable) not called for 365+ days
hardis:org:diagnose:unused-connected-apps	Find Connected Apps with no recent OAuth usage

Org Monitoring

Command	What an agent can do
hardis:org:monitor:all	Run all configured monitoring checks, generate reports, and send notifications
hardis:org:monitor:backup	Retrieve a full metadata backup of the org
hardis:org:monitor:errors	Check for Apex and Flow errors in the org
hardis:org:monitor:health-check	Run the Salesforce Security Health Check and report the score
hardis:org:monitor:limits	Check org limits and alert when thresholds are approaching

User Management

Command	What an agent can do
hardis:org:user:freeze	Freeze user logins (temporarily suspend access without deactivating)
hardis:org:user:unfreeze	Unfreeze previously frozen users to restore their access
hardis:org:user:activateinvalid	Fix `.invalid` email suffixes on sandbox users so they can log in

Data & Files Management

Command	What an agent can do
hardis:org:data:export	Export data from a Salesforce org using an SFDMU workspace configuration
hardis:org:data:import	Import structured data into a Salesforce org from an SFDMU workspace
hardis:org:data:delete	Delete data from a Salesforce org using an SFDMU workspace configuration
hardis:org:files:export	Mass-download files attached to Salesforce records
hardis:org:files:import	Mass-upload files and attach them to Salesforce records
hardis:org:multi-org-query	Run a SOQL query against multiple orgs and aggregate results
hardis:datacloud:sql-query	Run ad-hoc or predefined SQL queries on Data Cloud objects
hardis:datacloud:extract:agentforce-conversations	Export Agentforce conversation logs from Data Cloud for analysis
hardis:datacloud:extract:agentforce-feedback	Export user feedback records from Agentforce sessions in Data Cloud

Metadata Cleaning & Quality

Command	What an agent can do
hardis:project:clean:references	Remove hardcoded user references, minimize profiles, and apply other automated cleaning rules
hardis:project:clean:orgmissingitems	Remove metadata from the project that is absent from the target org
hardis:project:clean:profiles-extract	Extract profile access data into CSV / Excel persona-centric reports
hardis:project:clean:xml	Remove XML elements using glob patterns and XPath expressions
hardis:project:clean:emptyitems	Remove empty metadata XML items that produce unnecessary deployment noise
hardis:project:clean:filter-xml-content	Filter out specific XML nodes from metadata files using configurable rules
hardis:project:clean:flowpositions	Normalize Flow element coordinates to reduce position-only git diffs
hardis:project:clean:hiddenitems	Remove metadata items that are hidden / private in the org and not deployable
hardis:project:clean:listviews	Remove list views referencing unavailable fields or objects
hardis:project:clean:manageditems	Remove managed package metadata items from the local project
hardis:project:clean:minimizeprofiles	Strip profiles down to the minimum permissions needed for the project
hardis:project:clean:retrievefolders	Retrieve report and dashboard folder metadata to keep the project in sync with the org
hardis:project:clean:sensitive-metadatas	Remove sensitive values (credentials, tokens) from metadata before committing
hardis:project:clean:standarditems	Remove references to standard Salesforce items not needed in the project
hardis:project:clean:systemdebug	Strip `System.debug()` statements from Apex code before deployment
hardis:project:convert:profilestopermsets	Convert Profile permissions into equivalent Permission Sets
hardis:project:fix:profiletabs	Manage tab settings inside profile XML files
hardis:project:fix:v53flexipages	Fix Flexipage metadata incompatibilities introduced by API v53
hardis:org:fix:listviewmine	Fix list views whose scope `Mine` must be replaced with `Everything` for deployment
hardis:org:purge:flow	Delete obsolete Flow versions to reduce storage and technical debt
hardis:org:purge:apexlog	Delete accumulated Apex debug logs from an org
hardis:org:purge:profile	Remove permission attributes from Profiles after migrating to Permission Sets
hardis:org:generate:packagexmlfull	Generate a complete `package.xml` covering all metadata in an org, including managed packages
hardis:packagexml:append	Merge additional `package.xml` files into the project's main package.xml
hardis:packagexml:remove	Remove specific types or members from a `package.xml` file

Code Quality & Audit

Command	What an agent can do
hardis:lint:access	Check that all custom elements are accessible through at least one Permission Set or Profile
hardis:lint:unusedmetadatas	Find custom labels and permissions that are defined but never referenced in code
hardis:lint:missingattributes	Identify custom fields that have no description (documentation enforcement)
hardis:lint:metadatastatus	Detect inactive metadata components in local project files
hardis:project:lint	Run Mega-Linter across the full project for style, quality, and security checks
hardis:project:audit:apiversion	Find metadata deployed below a configurable API version threshold
hardis:project:audit:callincallout	Identify Apex methods performing both DML and HTTP callouts in the same transaction
hardis:project:audit:duplicatefiles	Detect duplicate metadata files in the project tree
hardis:project:audit:remotesites	Audit Remote Site Settings for completeness and security
hardis:project:metadata:findduplicates	Find duplicate metadata definitions across the project
hardis:misc:purge-references	Remove or replace stale string references across metadata files
hardis:org:test:apex	Run Apex tests in the target org and report pass / fail / coverage results

Package Management

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

Documentation Generation

Command	What an agent can do
hardis:doc:project2markdown	Generate the full Salesforce project documentation as Markdown - objects, flows, profiles, Apex, LWC, packages, and more
hardis:doc:object-field-usage	Measure field-level data completeness across sObjects for documentation and cleanup planning
hardis:doc:fieldusage	Display where custom fields are referenced across metadata components (impact analysis)
hardis:doc:extract:permsetgroups	Generate a detailed report of Permission Set Group assignments and included permission sets
hardis:doc:flow2markdown	Convert a Salesforce Flow metadata file into a human-readable Markdown description
hardis:doc:mkdocs-to-cf	Publish MkDocs-generated documentation to Cloudflare Pages
hardis:doc:mkdocs-to-confluence	Synchronize MkDocs documentation to a Confluence space
hardis:doc:mkdocs-to-salesforce	Publish MkDocs documentation as Salesforce Knowledge articles
hardis:doc:override-prompts	Manage prompt override files for customizing AI-generated documentation output
hardis:doc:packagexml2markdown	Convert a `package.xml` into a human-readable Markdown change summary
hardis:doc:plugin:generate	Generate reference documentation for a Salesforce CLI plugin

Git & Reporting

Command	What an agent can do
hardis:git:pull-requests:extract	Extract pull/merge request data from GitHub, GitLab, or Azure DevOps for reporting and auditing
hardis:misc:servicenow-report	Retrieve Salesforce user stories and enrich them with ServiceNow data
hardis:misc:custom-label-translations	Isolate and export specific custom label translations
hardis:misc:toml2csv	Convert TOML structured data files to CSV format for reporting

Community (Salesforce Sites)

Command	What an agent can do
hardis:org:community:update	Programmatically publish or unpublish a Salesforce Community