Back to the Developer Blog

    Deploying Apex classes from the terminal with the Agentia CLI

    Mattia Lucca

    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

    1. Why this exists
    2. Use case 1: org-to-org deployment with no Salesforce login
    3. Use case 2: a validation you can script
    4. Use case 3: letting a coding agent deploy, safely
    5. When to stay with sf
    6. 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 adv command 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 --yes in the CLI, or confirm: true over 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:

    1. Generate a PAT in Pipelines and run agentia auth set --adv "$PAT" --local in a test project.
    2. Pick two sandboxes and one small class, and run the create, validate and deploy sequence from use case 1.
    3. Point a coding agent at the same project and watch what it does with the confirmation guardrails.
    4. Tell us what you would change. What worked, what got in your way and which use case you would add are all useful.

    References

    From install to first commit, right in your IDE

    Agentia Headless is available for all Copado solutions. Install the Agentia CLI, connect it to your Copado account once, and run your pipeline from any IDE.

    1. Sign in with Copado

      New to Copado? Headless needs a Copado account. Start a free Agentia trial, then come back and install the CLI.

    2. Install the CLI

      $npm install -g @copado/agentia-cli

      Makes the agentia binary available system-wide.

    3. Run the setup wizard

      $agentia setup

      The wizard guides you through authentication, skills configuration, local quality gates and more.

    Companion IDE extensions are available for VS Code and, via Open VSX, for Cursor.