Run Command job

Behavior-level reference for diagnosing Run Command jobs.

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

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.exe on Windows, /bin/sh on 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 launched 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.

Configuration reference

Parameter	Type	Required	Default	Limits	Notes
command	string	Yes	—	1–65536 chars	The command line to run.
arguments	list of strings	No	none	≤100 items, each ≤8192 chars	Appended to the command.
workingDirectory	string	No	agent working directory	≤4096 chars	Directory to run in.
environment	name→value map	No	none	each value ≤32768 chars	Extra environment variables for the command.
shell	boolean	No	true	—	Run through the system shell (pipes/redirects) vs. direct process.
failOnError	boolean	No	true	—	true fails the job on a non-zero exit code; false never fails it on its exit code. Ignored when exitCriteria is set.
exitCriteria	list of conditions	No	none	≤5 conditions	Exit codes that mean failure. See Deciding success.
outputParsing	list of rules	No	none	≤5 rules	Search the job output for text and set an exit code. See Deciding success.

Every Run Command job has a fixed one-hour timeout. 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: 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:

1. Output parsing searches the job output and may rewrite the exit code. It never decides the outcome by itself.
2. 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 same model the legacy Windows LSAM command job has always used, now available on the Universal Agent's built-in job types.

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
Text 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 GE 8	8 matches, so the job fails.

Only the first and last 512 KB of each stream are searched

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.

Fail on Error off means the exit code can never fail the job

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 failOnError is false.
Failed — exit criteria matched	the effective code	A condition matched the effective code.
Failed — command error	the command's code	Command exited non-zero, no exit criteria are set, and failOnError is true.
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 command or program was not found or could not start.
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 below).
Stopped — timeout or cancel	128	The agent terminated the process. Criteria and rules are not applied — a job the platform stopped always fails.

Two exit-code details worth knowing before you read one

• 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.

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 SECRET or PASSWORD, 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.

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, shell, workingDirectory), and the agent OS.