Pipelines Advanced with Agentia CLI

Use the agentia adv command group to work with Copado Pipelines Advanced from a terminal, CI job, or compatible coding agent. You can inspect organizations, create and configure deployments, select components, validate and deploy changes, and monitor run history without switching to the Pipelines Advanced UI.

Pipelines Advanced commands are part of the Agentia CLI product preview. Commands, flags, and behavior can change before general availability.

What you can do

• Authenticate once with a Pipelines Advanced personal access token (PAT).
• Discover the regional Pipelines Advanced endpoint automatically.
• List and validate organizations available to the PAT user.
• Create and configure deployments between source and target organizations.
• Compare, select, add, and remove metadata components.
• Validate, deploy, quick deploy, cancel, and wait for runs.
• Use structured --json output in scripts and CI.
• Access the same operations through the local Agentia MCP server.

Prerequisites

• Node.js and npm.
• Agentia CLI installed from the supported beta channel.
• A Copado Pipelines Advanced PAT with access to the required organizations and deployments.

Install Agentia CLI:

npm install -g @copado/agentia-cli@beta --registry https://registry.npmjs.org --@copado:registry=https://registry.npmjs.org

Verify the installation:

agentia --version
agentia --help

Authenticate

The Pipelines Advanced PAT can initially be configured only with agentia auth set --adv. The CLI validates the PAT, discovers the regional endpoint, and stores the PAT in the operating system keychain. The endpoint is stored separately as non-secret configuration.

agentia auth set --adv <pat-token>

Authentication is global by default. Add --local to scope the credential to the current project and operating-system user:

agentia auth set --adv <pat-token> --local

The local PAT still stays in the system keychain. Only its opaque keychain account identifier and non-secret endpoint metadata are kept in the current user's gitignored project configuration.

For a non-standard Pipelines Advanced endpoint, provide the complete base URL:

agentia auth set --adv <pat-token> --adv-base-url https://<pipelines-advanced-host>

Do not put the PAT in command history, source files, committed configuration, or CI logs.

Inspect global and project-scoped configuration. Stored PATs are masked:

agentia auth get --adv

Validate the configured PAT against Pipelines Advanced:

agentia adv auth status
agentia adv auth status --json

Remove the global PAT and endpoint configuration (global is the default scope):

agentia auth unset --adv
agentia auth unset --adv --global

Remove authentication for the current project and user:

agentia auth unset --adv --local

--global and --local are mutually exclusive. Interactive execution prompts before removal. Non-interactive and JSON execution requires --yes (or -y):

agentia auth unset --adv --local --yes --json

Command conventions

IDs

Pipelines Advanced uses numeric organization and deployment IDs:

• <organization-id> identifies an organization visible to the PAT user.
• <deployment-id> identifies a Pipelines Advanced deployment. Deployment list output exposes the API flowId as id; use that value in subsequent commands.

JSON output

Every agentia adv command supports the global --json flag:

agentia adv deployment list --json

JSON mode writes structured output for automation and does not mix tables, spinners, or prompts into stdout.

Error output and exit codes

Successful commands exit with code 0. Input errors, API errors, timeouts, and completed runs that did not succeed exit nonzero:

• Exit 1 indicates an operation, provider request, timeout, or waited run failed.
• Exit 2 indicates invalid CLI use or missing explicit confirmation.

When --wait is used, validation, deploy, quick-deploy, and job wait exit 1 if the final run result is failed or cancelled. This makes shell controls such as set -e stop correctly. A successful cancellation request remains successful when the server reports the run as cancelled.

API errors in JSON mode include provider and request context plus the command transaction ID:

{
  "error": {
    "code": "flow_busy",
    "statusCode": 409,
    "requestMethod": "POST",
    "requestUrl": "https://<pipelines-advanced-host>/api/v3/flows/<deployment-id>/deploy",
    "name": "AdvGatewayError",
    "message": "The deployment is busy."
  },
  "transactionId": "<transaction-id>"
}

Common provider codes include action_in_progress, flow_busy, and quick_deploy_unavailable. Pipelines Advanced can return additional codes in the X-Error-Code response header.

CLI validation errors have a smaller error object but still include the transaction ID:

{
  "error": {
    "name": "Error",
    "message": "Expected an integer but received: invalid"
  },
  "transactionId": "<transaction-id>"
}

When a waited run finishes without succeeding, the JSON error includes the normalized job under error.result.job.

Waiting for runs

Validation, deployment, quick deployment, and cancellation are asynchronous. Add --wait to wait for the accepted run:

agentia adv deployment validate <deployment-id> --wait

Use these flags to control polling:

• --interval <seconds> sets the delay between status requests. The default is 3 seconds.
• --timeout <seconds> sets the maximum wait. The default is 3600 seconds.

You can also start an operation without --wait and monitor it later with agentia adv job get, list, or wait.

Confirmation

deployment deploy, deployment quick-deploy, and deployment cancel can change deployment state. Interactive terminal use prompts for confirmation. JSON and non-interactive use requires --yes:

agentia adv deployment deploy <deployment-id> --yes --json

End-to-end deployment workflow

The following workflow discovers organizations, creates a deployment, selects components, validates the deployment, and starts the deploy:

# 1. Find and validate organizations.
agentia adv organization list --json
agentia adv organization validate <source-org-id>
agentia adv organization validate <target-org-id>

# 2. Create a deployment.
agentia adv deployment create \
  --name release-1 \
  --source-org <source-org-id> \
  --target-org <target-org-id> \
  --json

# 3. Discover and compare component types.
agentia adv component types --json
agentia adv component refresh \
  --flow <deployment-id> \
  --type ApexClass,Flow
agentia adv component list \
  --flow <deployment-id> \
  --type ApexClass,Flow \
  --json

# 4. Select components.
agentia adv component add \
  <deployment-id> \
  --component ApexClass/MyClass \
  --component Flow/MyFlow \
  --json

# 5. Review and configure the deployment.
agentia adv component selected <deployment-id> --json
agentia adv deployment options \
  <deployment-id> \
  --set deployOptionsTestLevel=RUN_LOCAL_TESTS \
  --json

# 6. Validate and deploy.
agentia adv deployment validate \
  <deployment-id> \
  --wait \
  --json
agentia adv deployment deploy \
  <deployment-id> \
  --yes \
  --wait \
  --json

Authentication command

agentia adv auth status

Checks the configured PAT and returns non-secret token metadata, the resolved endpoint, the user name when available, and expiry warnings.

agentia adv auth status [--json]

Examples:

agentia adv auth status
agentia adv auth status --json

JSON output uses this result shape:

{
  "result": {
    "baseUrl": "https://<pipelines-advanced-host>",
    "token": {
      "name": "<token-name>",
      "hint": "<masked-hint>",
      "expiresAt": "<timestamp>",
      "lastUsedAt": "<timestamp>"
    },
    "userName": "<user-name>",
    "warnings": []
  },
  "status": 0,
  "transactionId": "<transaction-id>"
}

Optional token fields are omitted when the server does not return them. The PAT itself is never returned.

Organization commands

agentia adv organization list

Lists organizations visible to the configured PAT user.

agentia adv organization list [--json]

Example:

agentia adv organization list --json

agentia adv organization get

Returns one organization by ID.

agentia adv organization get <organization-id> [--json]

Example:

agentia adv organization get <organization-id> --json

agentia adv organization validate

Checks whether Pipelines Advanced can connect to an organization.

agentia adv organization validate <organization-id> [--json]

Example:

agentia adv organization validate <organization-id> --json

Deployment commands

agentia adv deployment list

Lists deployments visible to the configured PAT user.

agentia adv deployment list [--include-archived] [--json]

Flags:

• --include-archived includes archived deployments.

The Pipelines Advanced API returns at most 500 deployments and does not expose a filter or pagination input for this operation.

Examples:

agentia adv deployment list
agentia adv deployment list --include-archived --json

agentia adv deployment get

Returns one deployment, including its source and target organizations, selected component counts, and current deployment options.

agentia adv deployment get <deployment-id> [--json]

Example:

agentia adv deployment get <deployment-id> --json

agentia adv deployment create

Creates a deployment between two different organizations.

agentia adv deployment create \
  --name <name> \
  --source-org <source-org-id> \
  --target-org <target-org-id> \
  [--json]

Required flags:

• --name <name> sets the deployment name.
• --source-org <organization-id> sets the source organization.
• --target-org <organization-id> sets the target organization.

Example:

agentia adv deployment create \
  --name release-1 \
  --source-org <source-org-id> \
  --target-org <target-org-id> \
  --json

The source and target organization IDs must differ.

agentia adv deployment options

Updates deployment options. The command first reads the current options, merges the supplied values, and sends the complete options object because the Pipelines Advanced API replaces the object.

agentia adv deployment options <deployment-id> \
  [--set <name=value>...] \
  [--file <path>] \
  [--json]

Input flags are mutually exclusive:

• --set <name=value> sets one option. Repeat it for multiple options.
• --file <path> reads an object from a JSON file.

The CLI accepts option names supported by the Pipelines Advanced server. Read the current deployOptions object with agentia adv deployment get <deployment-id> --json before changing it. Common options include:

• deployOptionsIgnoreWarnings — boolean.
• deployOptionsTestLevel — string. Supported levels include NO_TEST_RUN, RUN_SPECIFIED_TESTS, RUN_LOCAL_TESTS, and RUN_ALL_TESTS_IN_ORG.

When RUN_SPECIFIED_TESTS is selected, configure the corresponding server-supported test class option for the deployment. For the underlying Salesforce meanings and constraints, see DeployOptions in the Metadata API Developer Guide.

--set converts the exact strings true, false, and null, then passes other non-empty values through JavaScript Number. Decimal, hexadecimal, and exponent notation therefore become numbers (16, 0x10, and 1e3 become 16, 16, and 1000). Values that do not produce a finite number remain strings. --file uses the JSON types written in the file.

Examples:

agentia adv deployment options \
  <deployment-id> \
  --set deployOptionsIgnoreWarnings=false

agentia adv deployment options \
  <deployment-id> \
  --set deployOptionsTestLevel=RUN_LOCAL_TESTS \
  --json

agentia adv deployment options \
  <deployment-id> \
  --file options.json \
  --json

Example options.json:

{
  "deployOptionsIgnoreWarnings": false,
  "deployOptionsTestLevel": "RUN_LOCAL_TESTS"
}

Use option names and values supported by your Pipelines Advanced environment.

agentia adv deployment validate

Starts a check-only validation run.

agentia adv deployment validate <deployment-id> \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

Examples:

agentia adv deployment validate <deployment-id>
agentia adv deployment validate <deployment-id> --wait --json

agentia adv deployment deploy

Starts a deployment run.

agentia adv deployment deploy <deployment-id> \
  [--yes] \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

Examples:

agentia adv deployment deploy <deployment-id>
agentia adv deployment deploy <deployment-id> --yes --wait --json

Use --yes in CI, JSON mode, or any non-interactive session.

agentia adv deployment quick-deploy

Starts a quick deploy for a deployment that is eligible for quick deployment.

agentia adv deployment quick-deploy <deployment-id> \
  [--backup] \
  [--yes] \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

Flags:

• --backup changes the server operation from quick deploy to backupThenDeploy. The returned action reflects backupThenDeploy; this is not a quick deploy preceded by an independent backup.
• --yes confirms the action without prompting and is required in CI, JSON mode, or non-interactive sessions.

Examples:

agentia adv deployment quick-deploy <deployment-id> --yes
agentia adv deployment quick-deploy <deployment-id> --backup --yes --wait --json

agentia adv deployment cancel

Requests cancellation of the current active run. The command fails when the deployment has no active run.

agentia adv deployment cancel <deployment-id> \
  [--yes] \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

Examples:

agentia adv deployment cancel <deployment-id>
agentia adv deployment cancel <deployment-id> --yes --wait --json

Component commands

agentia adv component types

Lists the component type views supported by Pipelines Advanced.

agentia adv component types [--json]

Example:

agentia adv component types --json

Run this command before component list or refresh operations when you do not know the exact component type name.

The same component type name can appear in more than one view. Treat the type name, not its view position, as the identifier used by component commands.

agentia adv component refresh

Refreshes the component comparison cache for one or more component types.

agentia adv component refresh \
  --flow <deployment-id> \
  --type <type[,type...]> \
  [--full] \
  [--json]

Required flags:

• --flow <deployment-id> identifies the deployment.
• --type <type[,type...]> supplies one or more comma-separated component type names.

Optional flags:

• --full deletes cached comparison data before refreshing.

Examples:

agentia adv component refresh \
  --flow <deployment-id> \
  --type ApexClass

agentia adv component refresh \
  --flow <deployment-id> \
  --type ApexClass,Flow \
  --full \
  --json

agentia adv component list

Lists source components available for selection and their comparison state.

agentia adv component list \
  --flow <deployment-id> \
  --type <type[,type...]> \
  [--include-managed-package] \
  [--json]

Required flags:

• --flow <deployment-id> identifies the deployment.
• --type <type[,type...]> supplies one or more comma-separated component type names.

Optional flags:

• --include-managed-package includes managed-package components.

Examples:

agentia adv component list \
  --flow <deployment-id> \
  --type ApexClass \
  --json

agentia adv component list \
  --flow <deployment-id> \
  --type ApexClass,ApexTrigger \
  --include-managed-package \
  --json

If entries remain in a Comparing or Unknown state, refresh those component types and list them again.

agentia adv component selected

Lists components currently selected for a deployment.

agentia adv component selected <deployment-id> [--json]

Example:

agentia adv component selected <deployment-id> --json

agentia adv component add

Adds one or more components to a deployment selection.

agentia adv component add <deployment-id> \
  [--component <Type/Name>...] \
  [--file <path>] \
  [--json-file <path>] \
  [--json]

Choose one input mode:

• --component <Type/Name> adds one component. Repeat the flag to add multiple components.
• --file <path> reads a text file containing one Type/Name entry per line.
• --json-file <path> reads a bare array of component objects from JSON.

Examples:

agentia adv component add \
  <deployment-id> \
  --component ApexClass/MyClass \
  --component ApexTrigger/MyTrigger

agentia adv component add <deployment-id> --file components.txt --json
agentia adv component add <deployment-id> --json-file components.json --json

Example components.txt:

ApexClass/MyClass
ApexTrigger/MyTrigger
Flow/MyFlow

Example components.json:

[
  {
    "type": "ApexClass",
    "fullName": "MyClass"
  },
  {
    "type": "Flow",
    "fullName": "MyFlow"
  }
]

The bare array can contain:

• Normalized {type, fullName} objects, optionally with excluded.
• Rows copied from agentia adv component list --json after extracting the result.components array.
• Provider-shaped {nodeType: {name}, fullName} objects.

Do not save the whole Agentia --json envelope as the input file; the top level must be an array. The input flag is named --json-file because --json is reserved for command output.

agentia adv component remove

Removes one or more components from a deployment selection.

agentia adv component remove <deployment-id> \
  [--component <Type/Name>...] \
  [--json-file <path>] \
  [--json]

Choose one input mode:

• --component <Type/Name> removes one component. Repeat the flag to remove multiple components.
• --json-file <path> reads a bare array of component objects from JSON.

Unlike component add, component remove has no text-file --file mode. Its JSON result field requested contains the component array submitted for removal; it is not a count.

Examples:

agentia adv component remove \
  <deployment-id> \
  --component ApexClass/MyClass

agentia adv component remove <deployment-id> --json-file components.json --json

Job commands

agentia adv job get

Returns the latest run for a deployment.

agentia adv job get <deployment-id> [--json]

Example:

agentia adv job get <deployment-id> --json

The normalized result identifies whether the run is still running, succeeded, failed, or was cancelled.

agentia adv job list

Lists deploy and quick-deploy run history for a deployment. Validation runs are not included in this history endpoint.

agentia adv job list <deployment-id> \
  [--page <number>] \
  [--page-size <number>] \
  [--json]

Flags:

• --page <number> selects a zero-based page. The default is 0.
• --page-size <number> controls rows per page. The default is 50. The server caps the effective page size at 100 and can reduce larger values without an error.

Examples:

agentia adv job list <deployment-id>
agentia adv job list <deployment-id> --page 0 --page-size 25 --json

agentia adv job wait

Waits for the latest run to finish and returns its final normalized result.

agentia adv job wait <deployment-id> \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

Examples:

agentia adv job wait <deployment-id>
agentia adv job wait <deployment-id> --interval 5 --timeout 1800 --json

CI example

This shell example validates and deploys an existing deployment. Configure the PAT on the build machine before running the job, and ensure the operating system provides secure keychain storage.

set -e

DEPLOYMENT_ID="<deployment-id>"

agentia adv auth status --json
agentia adv deployment validate \
  "$DEPLOYMENT_ID" \
  --wait \
  --interval 5 \
  --timeout 1800 \
  --json
agentia adv deployment deploy \
  "$DEPLOYMENT_ID" \
  --yes \
  --wait \
  --interval 5 \
  --timeout 1800 \
  --json

Local MCP tools

Start the local MCP server:

agentia mcp start

The server exposes 21 Pipelines Advanced tools that correspond to the CLI commands. Required arguments are shown without ?; optional arguments use ?.

MCP tool	Arguments
agentia_adv_auth_status	None
agentia_adv_organization_list	None
agentia_adv_organization_get	id: number
agentia_adv_organization_validate	id: number
agentia_adv_deployment_list	includeArchived?: boolean
agentia_adv_deployment_get	id: number
agentia_adv_deployment_create	name: string, sourceOrg: number, targetOrg: number
agentia_adv_deployment_options	id: number, set?: string[]
agentia_adv_deployment_validate	id: number, wait?: boolean, interval?: number, timeout?: number
agentia_adv_deployment_deploy	id: number, confirm: true, wait?: boolean, interval?: number, timeout?: number
agentia_adv_deployment_quick_deploy	id: number, confirm: true, backup?: boolean, wait?: boolean, interval?: number, timeout?: number
agentia_adv_deployment_cancel	id: number, confirm: true, wait?: boolean, interval?: number, timeout?: number
agentia_adv_component_types	None
agentia_adv_component_list	flow: number, type: string, includeManagedPackage?: boolean
agentia_adv_component_refresh	flow: number, type: string, full?: boolean
agentia_adv_component_selected	deploymentId: number
agentia_adv_component_add	deploymentId: number, components: Array<string | {type, fullName, excluded?}>
agentia_adv_component_remove	deploymentId: number, components: Array<string | {type, fullName, excluded?}>
agentia_adv_job_get	deploymentId: number
agentia_adv_job_list	deploymentId: number, page?: number, pageSize?: number
agentia_adv_job_wait	deploymentId: number, interval?: number, timeout?: number

type for component list and refresh is a comma-separated string. Component strings use Type/Name. MCP deployment options accepts set entries but does not read a local --file. Validation does not require confirm; deploy, quick deploy, and cancel do.

Examples:

{
  "tool": "agentia_adv_deployment_validate",
  "arguments": {
    "id": 1025,
    "wait": true,
    "timeout": 1800
  }
}

{
  "tool": "agentia_adv_component_add",
  "arguments": {
    "deploymentId": 1025,
    "components": [
      {
        "type": "ApexClass",
        "fullName": "MyClass"
      }
    ]
  }
}

The deployment_deploy, deployment_quick_deploy, and deployment_cancel MCP tools reject the operation unless the caller supplies confirm: true.

Security and behavior

• The PAT is stored in the operating system keychain, not in project configuration.
• ADV commands do not accept a PAT flag.
• Human-readable, JSON, debug, and MCP output redacts credential-like fields.
• Authentication status exposes only non-secret token metadata such as its name, hint, last-use time, and expiry.
• Provider errors are sanitized and bounded before they reach output.
• Gateway telemetry is best-effort and excludes the PAT, authorization headers, request bodies, and provider responses.
• API behavior is limited by the permissions of the configured PAT.

Troubleshooting

PAT is not configured

Configure it and verify the result:

agentia auth set --adv <pat-token>
agentia auth get --adv
agentia adv auth status

Endpoint discovery fails

Confirm that the PAT is valid, active, and not expired. Endpoint discovery retries another supported region only when a region reports that the PAT is invalid. Network, service, rate-limit, expired-token, and revoked-token errors are returned immediately.

For an approved non-standard environment, configure its HTTPS base URL explicitly:

agentia auth set \
  --adv <pat-token> \
  --adv-base-url https://<pipelines-advanced-host>

Unknown component type

List the type names supported by the environment:

agentia adv component types --json

Use the returned type name exactly in component list, refresh, add, and remove.

Component comparison does not finish

Refresh the affected component types, then list them again:

agentia adv component refresh \
  --flow <deployment-id> \
  --type <component-type> \
  --full
agentia adv component list \
  --flow <deployment-id> \
  --type <component-type> \
  --json

A wait operation times out

Inspect the latest run and its history:

agentia adv job get <deployment-id> --json
agentia adv job list <deployment-id> --json

Then retry job wait with a longer timeout when appropriate:

agentia adv job wait <deployment-id> --timeout 3600 --json

A destructive command fails in CI

Add --yes to deploy, quick-deploy, or cancel commands:

agentia adv deployment deploy <deployment-id> --yes --json

For MCP, supply confirm: true.

Output cannot be parsed

Add --json and parse stdout as JSON. Keep status messages and diagnostics from stderr separate in automation.

Command summary

• Authentication: adv auth status
• Organizations: adv organization list, get, validate
• Deployments: adv deployment list, get, create, options, validate, deploy, quick-deploy, cancel
• Components: adv component types, list, refresh, selected, add, remove
• Jobs: adv job get, list, wait

Run command-specific help at any time:

agentia adv deployment deploy --help
agentia adv component add --help
agentia adv job wait --help