Run Command job
- Synopsis
- Full Details
In briefA Run Command job runs one command line on a Universal Agent machine and captures its
output. By default it runs through the system shell, so pipes and redirects work. By default it
succeeds on exit code 0 and fails on anything else. Exit criteria and output parsing let
you change that rule when the command uses its own codes.
WhereIn Design › Workflows, open a workflow and open the job in the Job Editor (open its context menu on the canvas › Edit Job). On the Job Definition tab, choose Run Command as the job type, set the fields under Job Parameters, and pick a Universal Agent under Agent Assignment. The job output and its Termination text show what decided the outcome.
WhenUse a Run Command job when:
- the work is one command line, or one program with arguments;
- a command's own exit codes do not follow the usual "
0is success" rule; - a command exits
0but prints an error you need to catch.
When the logic is more than one line, use Run Script. On a legacy LSAM machine, use that machine's command job type — see LSAM commands.
How
- Choose Run Command as the job type and enter the Command.
- Add Arguments, a Working Directory or Environment Variables if the command needs them.
- Turn Run via Shell off only to start a program directly, with no shell features.
- Add Exit Criteria or Output Parsing rules if the default rule does not fit.
- Assign the job to a Universal Agent and save.
For the full steps, see Run a command.
- Output parsing runs first and can change the exit code. Exit criteria then judge that code.
- An exit criterion that matches means the job failed. With criteria set, Fail on Error is ignored.
- Output parsing is case sensitive and supports only
*and?, not regular expressions. The first matching rule wins. - The command does not get the agent's secret variables. Pass what it needs as job Environment Variables.
- Every Run Command job stops after one hour, and no setting changes that. A command the agent stops always fails, whatever the criteria say.
- Kill does not stop the command on a Universal Agent.
- Only the first and last 512 KB of each output stream are searched. A match in the middle of a large output is missed.
- With Fail on Error off and no exit criteria, the exit code can never fail the job.
Task walkthrough: Run a command. This page is the full configuration and troubleshooting reference.
The Run Command job runs a command line on the agent machine. It's a built-in job
type (builtin:command), so no setup or connection is required.
| Property | Value |
|---|---|
| Job type | Run Command (run-command) |
| Runs on | Universal Agent only |
| Operating systems | Windows, Linux, macOS |
| Connections required | None |
| Category | Script |
- How It Works
- Configuration Reference
- Deciding Success
- Outcomes
- Troubleshooting
How It Works
How it works
The agent runs the command on the agent machine and captures its output.
- Run via Shell on (default) — the command runs through the system shell (
cmd.exeon Windows,/bin/shon Linux/macOS), so pipes, redirects, and shell built-ins work. Any arguments are appended to the command and safely quoted. - Run via Shell off — the command is started directly as a process. Shell features are not available; the command must be an executable and arguments are passed to it directly.
Standard output and standard error are both captured; standard error is appended to the job
output under a --- STDERR --- marker. The agent also sets OPCON_WORK_ITEM_ID and
OPCON_CORRELATION_ID environment variables that the command can read.
Environment handling
The command inherits the agent's environment minus sensitive variables, which are filtered out before the command runs. Filtered variables are:
- any variable whose name contains
SECRETorPASSWORD, and - these known credential variables:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,DATABASE_URL,DB_PASSWORD,API_KEY,SECRET_KEY,PRIVATE_KEY,OPCON_CLIENT_SECRET.
Variables the Builder sets in the job's Environment Variables, plus the injected
OPCON_WORK_ITEM_ID and OPCON_CORRELATION_ID, are always passed. This filtering is by
design — a command cannot read the agent's stored secrets through its environment.
Configuration Reference
| Parameter | Required | Default | Limits | Notes |
|---|---|---|---|---|
| Command | Yes | — | 1–65536 characters | The command line to run. |
| Arguments | No | none | Up to 100 arguments, each up to 8192 characters | Add as many as you need, one per entry. Appended to the command. |
| Working Directory | No | agent working directory | Up to 4096 characters | Directory to run in. |
| Environment Variables | No | none | Each value up to 32768 characters | Extra environment variables for the command, each a name and a value. |
| Run via Shell | No | On | — | A switch. On runs the command through the system shell (pipes, redirects); off starts it directly as a process. |
| Fail on Error | No | On | — | A switch. On fails the job on a non-zero exit code; off never fails it on its exit code. Ignored when Exit Criteria are set. |
| Exit Criteria | No | none | Up to 5 conditions | Exit codes that mean failure. See Deciding success. |
| Output Parsing | No | none | Up to 5 rules | Search the job output for text and set an exit code. See Deciding success. |
The platform sends every Universal Agent job with a 3,600-second limit, and no setting on the job changes it. At the hour the agent stops the command (graceful stop, then a forced stop after 5 seconds) and the job fails with Command exceeded its timeout of 3600s and was terminated. Kill does not reach a Universal Agent, so it does not stop the command sooner — see How a Universal Agent takes and runs work.
Deciding Success
Deciding success: exit criteria and output parsing
By default the job succeeds on exit code 0 and fails on anything else. Exit criteria and
output parsing replace that rule when the command's own convention is different — an exit 3
that means "nothing to do", or a command that exits 0 and prints an error.
The two work in a fixed order, and that order is the whole model:
- Output parsing searches the job output and may rewrite the exit code. It never decides the outcome by itself.
- Exit criteria judge the resulting code — the effective exit code — and decide failure.
Exit criteria
Each condition is an operator and a whole number, and a condition that matches means the job
failed. That is the one thing here that reads backwards, and it is deliberate: Equal To 5
means fail when the command exits 5, not succeed when it does.
| Field | Values |
|---|---|
| Operator | Equal To, Not Equal To, Less Than, Greater Than, Less Than or Equal To, Greater Than or Equal To |
| Value | A whole number from −2,147,483,648 to 2,147,483,647 |
- Conditions are OR-ed: the first one that matches fails the job. If none matches, the job finished OK — including on a non-zero code.
- Up to five conditions. Leave the list empty to keep the default rule.
- With conditions set, Fail on Error is ignored — the criteria are the rule.
This is the basic model of the legacy LSAM command jobs, which also offer an Exit Criteria Result of Finish OK, a Range operator and up to 20 conditions.
Output parsing
Each rule searches the job output for text and, when it matches, sets an exit code that the exit criteria then judge.
| Field | Values |
|---|---|
| Search Operation | Contains or Does Not Contain |
| String To Find | 1–255 characters |
| Exit Code To Set | A whole number in the same range as above |
- Rules are evaluated in order, and the first match wins — later rules aren't consulted.
- Both standard output and standard error are searched.
- Matching is case sensitive and supports
*(any run of characters) and?(exactly one character). It is not a regular expression, so.,\and(are literal text. - A wildcard never spans a line break, so a search string containing a newline can never match.
- Up to five rules.
A worked example. A command that reports trouble in its output but still exits 0:
| Rule | Effect |
|---|---|
Contains ERROR, set exit code 8 | The job's effective exit code becomes 8. |
Exit criterion Greater Than or Equal To 8 | 8 matches, so the job fails. |
The agent keeps the first 512 KB and the last 512 KB of standard output, and the same of standard error. A job that produces more than 1 MB on a stream has its middle dropped, and a match that appears only there is missed. When that could have changed the outcome, the job output opens with a note saying so — so treat output parsing as unreliable on a job that logs heavily, and narrow what the command prints instead.
With Fail on Error off and no exit criteria, nothing judges the code at all. An output-parsing rule can still change the code the job reports, but it cannot make the job fail. To have a rule fail the job, pair it with an exit criterion that matches the code it sets.
Outcomes
The effective exit code below is the command's own code, or the code an output-parsing rule set.
| Result | Exit code | When |
|---|---|---|
| Success | 0 | Command exited 0, with nothing configured to say otherwise. |
| Success despite a non-zero exit | the effective code | Exit criteria are set and none matched, or Fail on Error is off. |
| Failed — exit criteria matched | the effective code | A condition matched the effective code. |
| Failed — command error | the effective code | The effective exit code is non-zero, no exit criteria are set, and Fail on Error is on. |
| Failed — invalid parameters | 1 | A parameter fails validation: an empty Command, a value over its limit, more than five conditions or rules, an unrecognised operator, or a value outside the whole-number range. |
| Failed — could not start | 1 | The program could not be started — with Run via Shell off, a program that is not found. With Run via Shell on the shell itself starts, so a command it cannot find fails as a command error with the shell's own non-zero exit code instead. |
| Failed — output parsing could not finish | the command's own code | A rule's search could not complete within the agent's matching budget (see the Troubleshooting tab). |
| Stopped — timeout or cancel | 128 | The agent terminated the process. Criteria and rules are not applied — a job the platform stopped always fails. |
- A process ended by a signal reports exit code 128, and that cannot be told apart from a process
that genuinely exited
128. - A job that fails with exit code 0 shows its return code as — rather than
0, so a failed job never displays a code that reads like success.
The job's Termination text names what decided the outcome — the rule that fired, the criterion that matched, or the command's own code — followed by whatever the command wrote to standard error.
Troubleshooting
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job fails immediately with "Invalid task definition" | Command empty, or a value over its limit | Correct the parameters (Builder). |
| Command works in a terminal but the job reports it can't start | Executable not on the agent's PATH, or wrong working directory | Confirm the command exists on the agent; set Working Directory; for agent setup escalate to the Administrator. |
| Pipes, redirects, or shell built-ins don't work | Run via Shell is off | Turn Run via Shell on (Builder). |
| Command can't see an environment variable (often a password/secret) | The variable was filtered by design | Pass it as a job Environment Variable, or use a connection-based connector for credentials (Builder / Administrator). |
| Job fails on a non-zero exit code that you consider acceptable | Fail on Error is on and no exit criteria are set | Set exit criteria that exclude that code, or turn Fail on Error off (Builder). |
| Job finishes OK on an exit code that should have failed it | Exit criteria are set and none of them matches that code — the criteria replace Fail on Error entirely | Add a condition that matches the code, remembering a match means failure (Builder). |
| An output-parsing rule never fires even though the text is in the output | The search is case sensitive, */? are the only wildcards, a wildcard can't cross a line break, or the text sits in the dropped middle of more than 1 MB of output | Match the case exactly, replace regular-expression syntax with */?, and reduce how much the command prints (Builder). |
| Job fails with "could not be evaluated within the allowed matching budget" | A long search string containing ? against output with a long repeating run | Replace the ? with *, which makes the search efficient (Builder). |
| A job the platform stopped is reported failed even though its exit criteria allow that code | Deliberate: a process the agent terminated bypasses criteria entirely | Make the command finish within the one-hour limit, rather than changing the criteria (Builder). |
| Job ends after one hour with exit code 128 | The command ran past the fixed one-hour timeout and was stopped | The limit can't be raised. Split the work, or make the command finish within the hour (Builder). |
| Job assigned but never runs | Target agent is not a Universal Agent | Reassign to a Universal Agent. |
Contact support when
- A command that exists on the agent and runs manually still fails to start as a job, with a permission or spawn error.
- Output is captured incorrectly, or exit codes don't match what the command actually returns.
Include the job output, the parameter values (Command, Arguments, Run via Shell, Working Directory), and the agent OS.