Agentia CLI: story → Git → Copado without the busywork

You’ve got a normal Salesforce change: add Account.Tag__c, a validation rule on it, and wire both into the Sales Team permission set. Here’s how Agentia CLI handles that without you babysitting Copado’s UI.

The loop

agentia cicd work create ...          # create the story
agentia cicd work set US-XXXX         # checkout feature/<story>, remember base + dev branch
# write the XML, then:
git add ... && git commit -m "US-XXXX: Tag field, rule, Sales Team perms"
agentia cicd work publish             # the important bit
agentia cicd work submit              # validate / open review
# …feedback looks good, ready to ship:
agentia cicd work submit --done       # promote + deploy to the next env, story finished

That’s it. Git stays the source of truth. Agentia is the glue to Copado.

Why work set matters

After create, work set puts you on feature/<story-name> and stores which base branch and which dev org branch this story uses. Later commands don’t need you to re-pass IDs, and starting the work from the official main branch ensures no other unwanted changes are added.

Why not just git push?

Push alone doesn’t register a Copado Commit, doesn’t fix the Story change list for nested XML, and doesn’t sync the remote branch Copado ties to your org.

work publish does all of that:

1. Checks you’re clean and on the right feature branch
2. Diffs nested parents (profiles, permission sets, etc.) vs the base
3. Pushes the feature branch
4. Registers the commits with Copado (with the right change-list corrections)
5. Merges into the recorded dev org branch and pushes that too

So: one command ≈ push + Copado commit registration + remote Git sync.

Nested metadata (the Sales Team gotcha)

Tag__c and TagValidation are normal files → they show up as normal adds.

Sales_Team.permissionset-meta.xml is different. One file, many permission blocks. Copado cares about the blocks (Account, Phone, Tag__c), not “ship the whole permission set blindly.”

Publish detects what actually changed inside that XML and marks those as RetrieveOnly permissions. The permission set itself still goes on the story (that’s what deploys). Removing a field permission revokes access — it does not delete the field. That’s the win vs path-only detection.

Need a nudge for a weird case? --permissions / --full-metadata exist. Most of the time you won’t need them.

When submit says stories are behind

On submit, Agentia checks your story’s next pipeline environment. If other user stories are already ahead there (and yours is behind), you’ll get a warning: promoting later will likely fight those commits, or your coworker's changes might interfere with your development.

Don’t ignore it. Run:

agentia cicd work environment-sync

That pulls the newest changes from the next environment back onto your dest/dev branch (and related story work) in one go. You update the branches quickly, resolve any pathspec conflicts once if they show up, and keep your feature work sitting on top of what’s already downstream.

Why bother now: when you eventually promote this story to the next environment, Git already knows about those other changes. Far fewer merge conflicts later — you paid the sync cost early, while the diff is still small and local.

After feedback: finish with --done

Plain work submit is the review/validate step. Once you’ve got feedback and the work is actually finished, run:

agentia cicd work submit --done

That promotes and deploys to the next environment and closes out the delivery for the story. Don’t use --done until you mean it — it’s the “ship it” button, not another dry check.

Why bother

• Same flow for humans and agents
• You keep writing DX metadata like you already do
• Copado’s change list stays accurate for nested parents
• Remote Git and the Story stay in sync without clicking through commit screens
• environment-sync keeps you current with the next env so promotion stays boring
• submit for review, submit --done when you’re ready to deploy and finish

TL;DR: implement in Git, work publish to register + sync with Copado, environment-sync if submit says you’re behind, work submit for review, then work submit --done when feedback is in and you want it in the next env.