Back to the Developer Blog

    From a fix to UAT from the terminal: work items in the Agentia CLI

    Mattia Lucca

    By Mattia Lucca, Lead Engineer at Copado

    Pipelines Advanced commands, demo walkthrough. Demo recorded on @copado/agentia-cli 1.13.0.

    TL;DR

    In our previous demo, a coding agent in Cursor deployed two Apex classes from one sandbox to another. Useful, but real teams rarely stop at one hop: a fix has to travel a shared route (Dev -> QA -> UAT), pass static analysis and tests along the way, and leave a trail that the rest of the team can read in the UI.

    In this short demo, the fix is already coded in the Dev sandbox (SimpleMonitoringController and its test). Without leaving Cursor, we ask the agent to define the Dev -> QA -> UAT pipeline, open work item DEMO-103, select the components, run static code analysis, require test coverage, and promote the change all the way to UAT. As before, the laptop holds no Salesforce login — only a Pipelines personal access token.

    In this article

    1. Why plain deployments weren't enough
    2. Use case 1: promoting a change across stages, not org pairs
    3. Use case 2: catching mistakes before Salesforce does
    4. Use case 3: quality evidence the agent can actually read
    5. What isn't in the recording
    6. Takeaway and next steps

    Why plain deployments weren't enough

    A one-off deployment between two orgs is fine for an ad-hoc move. As soon as a team ships regularly, three gaps show up:

    • Someone has to remember the route. If Dev -> QA -> UAT only lives in people's heads or in a CI YAML file, an agent (or a developer in a hurry) has to pick source and target org IDs by hand at every hop — and nothing stops them from skipping QA.
    • Feedback arrives too late. A typo in a component name or a silent coverage drop used to surface only after a Salesforce run failed, often without saying why it failed.
    • The UI and the terminal drift apart. Teams track work items, stages and approvals in Pipelines, not loose deployments. If the CLI can only create plain deployments, automated work looks like second-class traffic in the UI.

    This release brings pipelines, work items, static code analysis and richer feedback to agentia adv, so an agent or a script follows the same release process a human follows in the browser. Plain deployment commands stay around for direct two-org moves, and for now the new commands are CLI-only (the local MCP server keeps the original 21 ADV tools).

    Use case 1: promoting a change across stages, not org pairs

    Why it matters: the team defines the route once; every change then rides that route instead of re-specifying orgs at each step.

    In the demo, the agent creates the three-stage pipeline (Dev -> QA -> UAT), opens work item DEMO-103 on it with its issue key, and later promotes it to UAT with a single instruction. Under the hood, work-item deploy --to UAT walks the remaining stages in order, waiting for each hop to finish before starting the next, and stops immediately if a stage fails or requires an approval.

    Two details make this safe to hand to an agent:

    • Preflight path checks and explicit gates. Before touching any org, work-item deploy validates the full requested path — if --to is misspelled or crosses an unsupported Git stage, it stops before mutating anything. Reaching a final or production stage also requires naming it explicitly with --to, plus --yes in non-interactive runs, so a bare work-item deploy will not wander into the end of the pipeline on its own.
    • Automatic lifecycle sync. When UAT finishes, the work item closes automatically, matching what a teammate sees on the Pipelines board.

    Use case 2: catching mistakes before Salesforce does

    Why it matters: agents make typos and hallucinate names just like humans do; catching that in milliseconds beats waiting on a Salesforce deployment queue.

    In step 3 of the demo, we deliberately ask the agent to add three classes, one of them misspelled (SimpleMonitoringControler). Instead of failing later during deployment, component add returns a structured components_not_found warning straight from the source org's comparison cache.

    Watch what happens in the recording: nobody tells the agent how to recover. Because warnings are surfaced cleanly inside the --json envelope without corrupting JSON output, the agent reads the warning, checks what is in Dev, removes the misspelled entry on its own, and leaves a clean two-class selection. The same pattern now covers ignored deploy options, empty validations, and pipeline edits that leave already-open work items on their previous snapshot — small signals that turn an agent from a blind script runner into something that can self-correct.

    Use case 3: quality evidence the agent can actually read

    Why it matters: "deployment succeeded" is a weak bar; before promoting to UAT, you want to know whether static analysis is clean and whether your tests actually covered the class.

    Two additions do the work in the demo:

    • PMD static code analysis from the CLI. The agent triggers code-analysis run --wait on the work item and reads back severity counts and individual rule violations — the same run behind the Run Static Code Analysis button in the web UI, without opening a browser.
    • Per-class code coverage on the job result. Until now, a run that failed Salesforce's coverage threshold could come back as Failed with an empty failure list, leaving both humans and agents guessing. With deployOptionsIncludeCodeCoverage=true, job get now returns line coverage per class alongside any coverage warnings — in the demo, 1/1 test passing and 100% coverage on SimpleMonitoringController at both QA and UAT.

    What isn't in the recording

    To keep the walkthrough short and solo, we left out a few capabilities that shipped in the same release and are worth knowing about:

    • Stage approvals — pipelines can require minimum approvals and default reviewers per stage; work-item deploy stops cleanly with approval_required, and work-item approval request notifies the reviewers.
    • Moving back and sharing — work-item back steps a work item back one stage (resetting approvals), and work-item share manages team access from the terminal.
    • Pre/post deployment tasks and rollback — deployment-task attaches webhook or email steps to stages, and deployment rollback-preview / deployment rollback inspect and create rollbacks from deployment history.

    All flags, payloads and error codes are in the CLI reference.

    Takeaway and next steps

    What stood out to me while recording this one is how little glue prompt I had to write. In the first demo I was still steering the agent around individual orgs; here I described the release intent — "put this on a Dev -> QA -> UAT pipeline, check it, require coverage, take it to UAT" — and the guardrails lived in Pipelines and the CLI rather than in my prompt. Watching the agent catch my deliberate typo from a CLI warning and fix the selection without asking me was the moment the workflow clicked.

    If you want to try it on your own sandboxes:

    1. Update to @copado/agentia-cli 1.13.0 (or later) and connect a Pipelines PAT with agentia auth set --adv "$PAT" --local.
    2. Create a two- or three-sandbox pipeline, open a work item on a small Apex class + test pair, and let your coding agent drive it to the final stage.
    3. Try adding a stage approval or a deliberate mistake, and see how the agent reacts to the structured warnings and refusals.
    4. Tell us where it rough-edges — which step felt slow, what output the agent misread, or which part of your release process still forced you back to the browser.

    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.