How-to
quick guides.

Create the user story and note the returned ID (for example US-0042).

Set the active work item. This calls the CICD gateway work/set endpoint, fetches the base branch from origin, and creates or checks out feature/US-0042.

Make your changes in the org (custom field, page layout, flow), then refresh the metadata index and confirm the changes are detected.

Check metadata dependencies before committing, so no hidden dependency breaks the deployment.

Best practiceIf a dependency is missing from your change set, add it to the user story metadata selection before pushing. Missing dependencies are the most common cause of downstream deployment failures.

Run local quality gates. This executes .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) from the project root, generated by agentia setup.

Stage and commit your changes locally.

Push the feature branch and register the commits with Copado, then confirm the push was registered.

Best practicework push publishes your commits to the remote branch and registers them in Copado. It does not start a promotion.

Submit for validation. This triggers a validation promotion and deployment (quality gates plus pull request).

Once validation passes, mark the work item done to promote and deploy it into the pipeline.

Create the user story and note the returned ID (for example US-0087).

Set the active work item. The command creates feature/US-0087-cpq-discount-tier-field from the root of the repository linked to the CPQ pipeline.

Add the field (for example SBQQ__Quote__c.Discount_Tier__c), update the Quote Template in the CPQ editor, save in the org, then refresh the metadata index.

List the changed CPQ metadata, compare the field between Dev and Integration, and check dependencies for price or product rules referencing the new field.

Best practiceCPQ metadata is highly interconnected. Price rules, product rules, and quote templates that reference a new field must be included in the same user story or deployed first.

Stage and commit your changes locally.

Submit for validation. This runs local quality gates, pushes the branch, registers commits, and triggers a validation promotion.

Once validation passes, mark the work item done to promote and deploy to Integration, then check the story with work status. It prints the user story plus its latest jobs (commit, validate, promote and deploy) with status and error message, so you do not need separate promotion commands.

Best practiceIf a job shows status Error, the message in the status output tells you what to fix (for example a merge conflict on the promotion, or a duplicate value on commit). Use agentia cicd job log get <job-id> only when you need the full log.

Confirm CRT readiness. CRT authentication is separate from Copado CI/CD and needs a PAK, a CRT domain, and a positive organization ID.

Best practiceGate automation on ready: true, not on set. set only means a credential exists; ready means the effective PAK, domain, and organization are all usable. Fix anything listed in missing or issues before continuing.

Find the CRT project and the job you need.

List the files attached to the job and download the script to an explicit directory, then open the .robot file in VS Code or Cursor.

Best practiceFor Git-backed jobs, check the reference and credential wiring with agentia testing job refs <your-job-id> --project <your-crt-project-id> --shared-credentials --json.

Run the job and wait for a terminal result, capturing artifacts and xUnit for CI. For Git-backed jobs, target the branch holding the script.

Best practice--stream-logs and --watch are for a human terminal and cannot be combined with --json. A --datatable run cannot be combined with --wait-for-result, --stream-logs, --save-artifacts, or --xunit.

Inspect the result and the logs. Use latest or search when you do not have the build ID at hand.

Best practiceLook for FAIL lines and the associated error message to pinpoint the broken keyword. Use agentia testing build search --project <your-crt-project-id> --job <your-job-id> --status failed --page-size 20 --json to review failure history, and agentia testing build abort <your-build-id> --project <your-crt-project-id> --yes to stop a run you no longer need.

Reproduce the failing step interactively when the log is not enough. Live testing lets you execute one keyword at a time against the session.

Best practiceagentia testing live view and the long-running agentia testing live recorder are terminal-only. Common fixes are updating a locator that changed in the UI, adjusting a wait condition or timeout, and correcting a variable reference or keyword argument.

Upload the corrected script and re-run to confirm the fix. Preview the file operations first with --dry-run.

Best practiceFor Git-backed CRT jobs, commit the fixed .robot file to the feature branch and point the job at that branch instead of uploading directly: agentia testing job update <your-job-id> --project <your-crt-project-id> --git-branch feature/fix-login-test. Keep secrets out of arguments — use agentia testing variable create … --value-stdin for sensitive values. To run this suite on a cadence, add agentia testing job schedule set <your-job-id> --project <your-crt-project-id> --cron "0 6 * * 1-5" --timezone UTC --record failed --json.

Start the MCP server from the repository root. It exposes 50+ Agentia tools to your AI client; in Cursor, reload MCP servers after the first setup so the tools appear.

Best practiceThe MCP server must be started from the root of the repository linked to your Copado pipeline. work set, work push, and related tools operate on the Git repo in the server's working directory.

Find the failing job, get the step breakdown, and retrieve the execution log. In Cursor, ask the Build Agent: "Use agentia_job_list to find my latest failed job, then get the log and tell me why the trigger is failing."

Retrieve the trigger and its handler class from the org. In Cursor, the agent does this with agentia_metadata_content_get.

With the log and source in context, prompt the Build Agent: "The job log shows a System.NullPointerException on line 42 of AccountTriggerHandler. The trigger fires on before update. Analyze the handler, identify the null reference, and propose a fix that follows the bulkification pattern and uses with sharing." Review the proposed change in the editor diff view.

Best practiceAlways review AI-generated Apex before committing. Check that the fix handles bulk scenarios (no SOQL or DML in loops), preserves the with sharing declaration, includes a null guard for the identified field, and does not introduce recursion.

Create or set the work item, then stage and commit the fixed files.

Run local quality gates, push, and submit for validation. work submit only validates and runs the quality gates, it does not deploy.

Best practiceDo not skip validation for trigger fixes; a null pointer in a trigger can cascade across bulk operations.

Once validation passes, mark the work item done to promote and deploy the fix, then confirm with work status, which lists the story and its latest jobs with status and error message.

Install the CLI beta.

Authenticate and verify with placeholders.

Best practiceagentia auth stores CLI/API credentials; agentia cicd credential manages Copado environment credential records. Robotic Testing and AI have their own authentication contexts.

Create the skill packs you need. With no pack selector, all three packs (CICD, Testing, AI) are created.

Best practice--target agents writes .agents/skills and is the portable default for headless runs; cursor writes .cursor/skills and claude writes .claude/skills. --target is repeatable when a project intentionally keeps more than one host-specific copy.

Configure MCP so the agent also has native Agentia tools.

Best practiceMCP gives the agent tools. Agentia Skills give it the operating playbook. Install both when the agent should execute Agentia workflows safely from the IDE.

Ask the agent to inspect before mutating: "Use the Agentia CICD skill to inspect my assigned Story and explain the local delivery flow. Do not promote anything."

Demonstrate one CI/CD read, one Robotic Testing read, and one AI ask.

Refresh the skills after you upgrade the CLI.

Best practiceupdate refreshes Agentia-managed files and restores missing managed files. A file without the Agentia managed marker is never overwritten; --force replaces a conflicting unmanaged file and should be used deliberately as recovery only.