Deploying Apex classes from the terminal with the Agentia CLI

By Mattia Lucca, Lead Engineer at Copado
Pipelines Advanced commands, demo walkthrough. Draft, 15 Oct 2026. Demo recorded on @copado/agentia-cli 1.0.0-beta.6; state checked against 1.0.0-beta.7.
TL;DR
In the demo, a developer asks a coding agent in Cursor: "Deploy the two Apex classes TestbookCalc and TestbookCalcTest from Squad4 to Alchemy." The agent uses the Agentia CLI to drive Pipelines Advanced: it creates the deployment, validates, deploys and reads back the result. The Cursor project has no Salesforce connection. Both orgs are reached through Pipelines, so the machine holds one token and no Salesforce login.
If you move changes between orgs as a team, this is a way to do it from a script or an agent without sharing Salesforce credentials. If you are one developer deploying your own project to your own sandbox, sf is simpler (see When to stay with sf).
In this article
- Why this exists
- Use case 1: org-to-org deployment with no Salesforce login
- Use case 2: a validation you can script
- Use case 3: letting a coding agent deploy, safely
- When to stay with
sf - Takeaway and next steps
Why this exists
Deployments between Salesforce orgs usually need three things on whoever runs them: a Salesforce login per org, a local project to retrieve into, and some way for the rest of the team to see what happened. That is manageable for one person. It gets awkward with several orgs, several people, CI runners and now coding agents, because every new runner or agent means another set of credentials to hand out and another place where a deployment can happen without anyone seeing it.
Pipelines already holds the org connections and the run history. The CLI exposes that to the terminal, so scripts and agents work through Pipelines instead of around it.
Use case 1: org-to-org deployment with no Salesforce login
Why it matters: the credentials that can touch your orgs stay in Pipelines, not on laptops and CI runners.
Authentication is a personal access token (PAT) generated in Pipelines. The CLI validates it, stores it in the OS keychain, and the project keeps only an opaque keychain reference in a git-ignored file:
agentia auth set --adv "$PAT" --local
--local limits the credential to the current project and OS user. In the demo the token came from the project's .env into a shell variable, so it never landed in shell history.
The deployment itself is retrieved from the source org and deployed on the server side, so the classes never have to be retrieved into a local project. The core of the demo is three commands:
agentia adv deployment create --name <name> --source-org <source-org-id> --target-org <target-org-id> --json
agentia adv component add <deployment-id> --component ApexClass/TestbookCalc --component ApexClass/TestbookCalcTest
agentia adv deployment deploy <deployment-id> --yes --wait --json
The full command list is in the CLI reference.
The deployment also shows up in the Pipelines UI with its status, and the job JSON names the user who ran it (runBy). Someone who was not at the terminal can still see what ran.
Use case 2: a validation you can script
Why it matters: you want to know a deployment will pass before you run it, and to reuse that result instead of paying for the same test run twice.
Validation is check-only and runs the tests you choose. In the demo only the test class ran, with code coverage on:
agentia adv deployment options <deployment-id> \
--set deployOptionsTestLevel=RUN_SPECIFIED_TESTS \
--set deployOptionsRunTests=TestbookCalcTest \
--set deployOptionsIncludeCodeCoverage=true --json
agentia adv deployment validate <deployment-id> --wait --json
The --wait flag blocks until the result is ready, so a script can branch on it. The job JSON includes canQuickDeploy, which says whether the validated run can be quick-deployed, reusing the validation instead of re-running the tests:
agentia adv deployment quick-deploy <deployment-id> --yes --wait --json
Use case 3: letting a coding agent deploy, safely
Why it matters: an agent that can deploy is useful, but only if it cannot deploy by accident and cannot leak the keys.
- Every
advcommand has--json, and the same operations are exposed as 21 MCP tools, so an agent does not have to parse human-readable output. - Destructive actions need explicit confirmation. Deploy, quick-deploy and cancel refuse to run without
--yesin the CLI, orconfirm: trueover MCP. The test runs confirmed the refusal without--yes. - Credentials stay out of output. In about 430 CLI calls during testing, the PAT never appeared in any output, and provider errors are sanitized before they reach the terminal.
When to stay with sf
The Salesforce CLI is free, mature and fast. For one developer deploying their own project to their own sandbox, it is simpler, and Pipelines should not be pitched for that case. Pipelines Advanced earns its place when a team works across several orgs and needs no shared Salesforce credentials, a shared run history and access levels per org.
Takeaway and next steps
What I took away from the demo is less about the commands than about where the trust sits. Once the agent can only act through a scoped token and has to be told explicitly to deploy, I was comfortable letting it run the whole sequence, and I could still see the result in the Pipelines UI afterwards. That is the part I would not get from handing the agent an sf login.
The adv commands are in product preview, so commands and flags can still change. This is a good moment to try them and tell us what is missing.
If you want to try it:
- Generate a PAT in Pipelines and run
agentia auth set --adv "$PAT" --localin a test project. - Pick two sandboxes and one small class, and run the create, validate and deploy sequence from use case 1.
- Point a coding agent at the same project and watch what it does with the confirmation guardrails.
- Tell us what you would change. What worked, what got in your way and which use case you would add are all useful.
References
- Copado Developer Portal, Agentia CLI reference, Pipelines Advanced section: https://developer.copado.com/docs#cli-reference