Meet Agentia: the successor to the Copado CLI
By Carlos García Abella
If you build Salesforce delivery pipelines with Copado, you may have used sf copado ... to bind a user story, push commits and submit work from your terminal. That plugin, @copado/copado-cli, is now deprecated. Its successor is Agentia, and it does more than the old plugin.
This article covers what changed and how the commands map. It ends with a migration path you can follow in an afternoon.
Here's what we'll cover:
- What is Agentia?
- What's better
- Legacy CLI vs Agentia: commit and promote
- Command comparison
- Migration path
- Start now
What is Agentia?
The legacy Copado CLI was a Salesforce CLI plugin. You installed it with sf plugins install, and it only existed inside sf.
Agentia is a standalone tool:
npm install -g @copado/agentia-cli
agentia setup
It talks to Copado through the CICD gateway and keeps your credentials in the system keychain. It covers the whole developer loop: select a story, commit, publish, validate, promote and deploy. It also adds capabilities the plugin never had, listed below.
You don't need to uninstall the Salesforce CLI. sf is still the tool for retrieving and deploying metadata against your development org. Agentia handles the Copado side.
What's better
| Capability | Legacy sf copado | Agentia |
|---|---|---|
| Form factor | sf plugin | Standalone CLI, plus a local MCP server for AI tools |
| Nested metadata (Profiles, Permission Sets, Workflows, Labels…) | Copado added the parent file but not the nested component, so the change wasn't deployed. CustomObject nested components worked only in Source Format pipelines. | work publish detects nested changes automatically and registers them |
| Find and replace (environment variables, YAML) | Not supported in a CLI commit | Applied locally during work publish |
| Local quality gates | None | work test, run automatically on work submit |
| Preview before publishing | None | work publish --dry-run |
| Branch sync with the next environment | Not covered | work environment-sync with --continue and --abort for conflicts |
| Cloud commit and cloud promotion, like the Copado UI | Not available | cloud commit and cloud promote |
| Status of a story and its jobs | story display, job status | work status shows the story with its related job executions |
| Machine-readable output | Limited | --json on every command |
Nested metadata
This is the biggest practical gain. With the old CLI, committing a change to a Profile or Permission Set meant switching to the Copado UI.
agentia cicd work publish inspects the branch and works out which nested components changed. For example, it finds the CustomField behind a profile field-permission edit. It supports these parent types:
- Profile, PermissionSet and MutingPermissionSet
- CustomObject and CustomObjectTranslation
- CustomLabels, Translations and Workflow
- Assignment, AutoResponse, Escalation, Matching and Sharing rules
You can override the detection when you need to:
# Force specific nested items to be retrieved
agentia cicd work publish --permissions "CustomField:Account.SLA__c,ApexClass:AccountService"
# Send complete files instead of decomposing them
agentia cicd work publish --full-metadata "Profile:Sales_User,PermissionSet:Sales_Onboarding"
# Opt out
agentia cicd work publish --skip-nested-metadata-detection
Local quality gates and a safer publish
work submit runs a project-root script, .agentia_quality_gates.sh on macOS and Linux or .agentia_quality_gates.cmd on Windows, before it submits. You can run the same script yourself with work test.
--apex-test-classes passes a list of test classes to that script. --skip-local-tests skips it.
Pipeline quality gates still run on the server, as before. They are configured through Extension Configurations: Apex tests, compliance scan, pull request, manual approval, static code analysis and others. They run on validation and promotion after work submit.
work publish --dry-run shows what would be registered without committing, pushing or registering anything.
Legacy CLI vs Agentia: commit and promote
The legacy Copado CLI's commit workflow was local: you created Git commits on your machine, then used sf copado story push to push and register them in Copado. Agentia carries that workflow forward with agentia cicd work publish and adds a cloud commit option, so you can also ask Copado to create the commit as it does in the UI.
Here's how the old workflow compares with Agentia's local and cloud options:
| Action | Legacy Copado CLI | Agentia local workflow | Agentia cloud workflow (like the Copado UI) |
|---|---|---|---|
| Commit | git commit, then sf copado story push pushes and registers the commits | git commit, then agentia cicd work publish pushes and registers the commits, with nested metadata detection and find-and-replace | agentia cicd cloud commit asks Copado to create the commit for a user story |
| Promote | sf copado story submit -d requests promotion and deployment through Copado; no local promotion command | agentia cicd work promote merges branches on your machine (experimental; skips Quality Gates) | agentia cicd cloud promote runs the Copado Promotion; add --deploy to deploy too |
The legacy CLI's local commit workflow should not be confused with local promotion: its submission command could trigger promotion and deployment through Copado. Agentia adds a dedicated cloud promotion command and an experimental local promotion option.
Commit
Agentia local commit: the successor to sf copado story push. You commit in Git, then run work publish. It pushes the feature branch and registers your commits in Copado. It also applies find-and-replace and detects nested metadata, extending the familiar local commit workflow.
Local commit with the legacy Copado CLI was limited. sf copado story push could push your Git commits to the feature branch and send the changed files to Copado, but little more. Agentia's work publish does the same job with more care:
Legacy sf copado story push | Agentia work publish | |
|---|---|---|
| What it registers | Every file from each pending commit, including merged-in base branch content, unless you chose --strategy scoped | Only the commits in origin/<base>..HEAD, so history that exists only on the base branch is ignored |
| Nested metadata (Profile, PermissionSet, Workflow, Labels…) | Not supported: the parent file was added but the nested component was not deployed | Detected automatically, with --permissions and --full-metadata overrides |
| Environment variables and YAML find-and-replace | Not supported | Applied locally and committed as a follow-up commit |
| Preview | None | --dry-run shows what would be registered, without pushing or registering anything |
| Environment branch | Merged into the environment branch, with --force available to force-push it | Feature branch merged into the recorded dev org branch |
| Empty commits | Nothing to register: stops with "No new commits to push" | Fails with "No changes to publish", unless --permissions or --full-metadata is set, which creates an empty commit so Copado has a tip commit |
| Evidence | Console output only | The command output is uploaded as a Salesforce File on the user story |
In short, the legacy CLI could move files to Copado. Agentia understands what is inside them and prepares them for the pipeline.
Agentia cloud commit: an additional option. Unlike the legacy CLI's local commit workflow, cloud commit asks Copado to create the commit, like the Commit action in the UI. You describe what to commit, either with flags or a JSON body, and Copado runs the commit job.
agentia cicd cloud commit \
--message "Commit AccountService" \
--metadata-name AccountService \
--metadata-type ApexClass \
--metadata-category SFDX \
--action Add \
--wait
work commit still exists as a hidden compatibility alias of cloud commit. In new scripts, use cloud commit.
Promote
Local promote. work promote creates the promotion and merges each feature/<name> branch into a promotion branch on your machine. It is experimental and skips Quality Gates, so it needs enableLocalPromote: true in .agentia/config.json. It can validate or deploy through sf project deploy start with --validate or --deploy. It also handles merge conflicts with --continue and --abort.
Cloud promote. cloud promote promotes the story through its Copado Promotion, like the UI. If no promotion contains the story, it creates a forward draft promotion, adds the story and runs it. It promotes only unless you pass --deploy, which promotes and deploys.
agentia cicd cloud promote US-0001 --deploy
Use cloud promote when you want the pipeline's normal behavior and Quality Gates. Use local promote only when you understand that it skips them.
Command comparison
| Step | Legacy CLI | Agentia |
|---|---|---|
| Authenticate | sf org login web, then sf copado auth set -u <username> | agentia setup (or agentia auth set --cicd <api-key>) |
| Set defaults | No equivalent (sf copado config set only stored list view, external Id and forceignore settings) | agentia cicd project default set |
| Select the story | sf copado story set -s <name> | agentia cicd work set <US-XXXX> |
| Override base branch | story set --base-branch | work set --base-branch |
| Retrieve and deploy metadata | sf project ... | Unchanged: sf project retrieve start and sf project deploy start, or VS Code |
| Commit | git add, git commit | Unchanged |
| Push and register (local commit) | sf copado story push | agentia cicd work publish (work push is a compatibility alias) |
| Commit in the cloud, like the UI | Not available | agentia cicd cloud commit |
| Validate | sf copado story submit -v | agentia cicd work submit |
| Promote and deploy | sf copado story submit -d | agentia cicd work submit --done (or work done) |
| Promote in the cloud, like the UI | Not available | agentia cicd cloud promote |
| Promote locally | Not available | agentia cicd work promote (experimental) |
| Flag as Ready to Promote | sf copado story submit -p | No direct equivalent (see below) |
| Check status | sf copado story display, sf copado job status | agentia cicd work status |
| Sync with next environment | Not available | agentia cicd work environment-sync |
| Clear the active story | Not available | agentia cicd work set --none |
Two differences to know about
Authentication works differently. The legacy plugin never used a Copado API key. It linked an sf org you had already logged in to, and called Copado using that Salesforce session. Agentia authenticates with a Copado API key stored in your keychain. Get one from your Copado admin before you start. You still log in to your dev org with sf, but only for retrieve and deploy.
-p has no direct equivalent. In the old CLI, story submit -p only flagged the story as Ready to Promote and did not create a promotion. Agentia's --done promotes and deploys, so it matches -d, not -p.
Migration path
1. Install and authenticate.
npm install -g @copado/agentia-cli
agentia setup
agentia setup replaces sf copado auth set. It is interactive. It guides CICD, AI and CRT authentication, configures MCP for Cursor and Claude Code, and sets up local quality gates and agent skills. Use agentia setup --skip-auth to skip the authentication step.
2. Set project defaults.
agentia cicd project default set --project <project> --environment <env> --credential <credential>
Defaults save you repeating options on commands such as work create and work list. The set, publish and submit flow uses the active story that work set records.
3. Remap your commands.
| Old | New |
|---|---|
story set | work set |
story push | work publish |
story submit -v | work submit |
story submit -d | work submit --done |
4. Retire your UI workarounds.
If you committed profiles, permission sets, workflows or labels through the Copado UI because the CLI couldn't handle them, try them with work publish. Check the detection on a test story first, using --dry-run. If you only need a UI-style commit from the terminal, cloud commit does that. The old advice still applies: don't commit the same component from both the UI and the CLI.
5. Keep the order.
agentia cicd work set US-0001 # select the story and branch
# retrieve/deploy with sf, then:
git add . && git commit -m "US-0001 Update account logic"
agentia cicd work publish # push and register in Copado
agentia cicd work submit # validate
agentia cicd work environment-sync # only if warned about stories ahead
agentia cicd work submit --done # promote and deploy
Start now
The old plugin still installs, but it is deprecated and gets no new features. Agentia is where Copado's CLI work is going. Install it with npm install -g @copado/agentia-cli, run agentia setup, and try the full flow on a test story.