Create a Command Line package¶

A Command Line package runs an executable or script on one of your own machines as a step in an orchestration flow. Use it for work that has to happen on your network and with your own tooling: running an SSIS package with dtexec, calling sqlcmd, driving a vendor's command-line utility, moving files between shares.

Standard output and standard error are both captured in the execution log.

Before you start¶

You need:

• permission to create packages in the workspace
• an O&DQ Gateway installed and reachable
• to know which identity the gateway service runs as, because that is the account your command will run under — not your own

Steps¶

1. Create the package¶

Go to Orchestration → Packages, select Create, and choose Command Line from the Scripts & commands area.

The new package opens on the Definition tab with the execution connection already filled in. Check the Execution connection, and select a different gateway if the pre-selected one is not the machine you want.

2. Start from a template, or write the command yourself¶

Use template offers six starting points, which fill in the command with the right switches and leave you to replace the paths:

Picking a template when the Command field already has content asks you to confirm before it overwrites what is there. The working directory is only replaced if the template itself specifies one.

3. Fill in the command and working directory¶

• Command — the executable and its arguments, as you would type them at a prompt
• Working directory — optional. If empty, the command runs in the working directory of the execution engine (epcmd), which is rarely what you want for a script that uses relative paths. Maximum 120 characters.

powershell.exe -ExecutionPolicy Bypass -File .\Export-SalesExtract.ps1 -Environment {$EnvironmentName}

{$EnvironmentName} is a global parameter reference. Global parameters are substituted into the command before the process starts, so you can keep paths, server names and credentials out of the package itself. Use Insert Parameter to pick one rather than typing the token by hand.

4. Optional: a separate command per environment¶

By default one command runs everywhere. Turning on Separate Development / Test / Production settings replaces that with an environment tab strip, and each environment gets its own gateway, command and working directory.

Two things are worth knowing before you switch it on:

Values are not copied across. Switching separation on leaves Test and Production empty rather than seeding them from Development — deliberately, so a production command is never created by accident. Use Copy from to pull one environment's values into another when that is what you want.

The package becomes incomplete. Required fields go from 2 to 6 — a gateway and a command for each of the three environments — so the completion badge drops and Save stays unavailable until all three are filled in. Hover Save to see exactly what is missing.

5. Save¶

Select Save. The package is stored as a Draft until you publish it.

How success and failure are decided¶

The command runs as a real process, and a non-zero exit code fails the package. That is the whole contract: exit 0 for success, anything else for failure.

This differs from the PowerShell package type, and the difference catches people out. A PowerShell package runs its script inside the execution engine's own process, so exit 1 never becomes a process exit code and the package still reports success — which is why that type needs throw instead. A Command Line package that invokes powershell.exe starts a genuine process, so there exit 1 works as expected.

If you are moving a script from a PowerShell package to a Command Line package, that is one of the few behavioural differences to check.

Examples¶

Run an SSIS package from the file system¶

"C:\Program Files\Microsoft SQL Server\160\DTS\Binn\dtexec.exe" /F "D:\ssis\LoadSales.dtsx" /CHECKPOINTING OFF /REPORTING EWCDI

Run a stored procedure with sqlcmd¶

sqlcmd -S {$SqlServerName} -d Warehouse -E -b -Q "EXEC dbo.usp_RebuildIndexes"

-b matters: without it sqlcmd returns 0 even when the batch fails, and the package will report success over a failed procedure.

Call a script with a relative path¶

Command:

powershell.exe -ExecutionPolicy Bypass -File .\Export-SalesExtract.ps1

Working directory:

D:\TimeXtender\scripts

Archive files after a load¶

robocopy D:\exports \\fileserver\archive\sales *.csv /MOV /R:2 /W:5

robocopy uses exit codes 0–7 for success and 8+ for failure, so a successful copy can still return a non-zero code and fail the package. Wrap it in a script that normalises the exit code if you use it here.

Best practices¶

Use absolute paths for the executable, relative paths for its arguments. Set the working directory once and let the script's own paths hang off it.

Check what your tool returns on failure. Command-line tools are inconsistent about exit codes — sqlcmd needs -b, robocopy uses a bitmask. Verify rather than assume, or the package will report success over a failure.

Put machine-specific values in global parameters. Server names and share paths differ between environments; the command should not have to.

Reach for separated settings only when the command genuinely differs. If only a value changes, a global parameter is simpler than three commands to maintain.

Quote paths containing spaces, including in the working directory.

Remember whose account this runs as. The gateway service account, not you. It is the most common reason a command that works in your own console fails in a package.

Secrets in the execution log¶

If your command uses a global parameter that holds a password, token or credential-bearing path, the execution log shows the parameter reference — {$MyPassword} — not what it resolved to.

That matters because an execution log is not transient: it appears in TDP, in the error-description window in Desktop, and a copy is retained in history indefinitely. Substitution is applied when the command runs, not when it is logged, so the resolved value of an encrypted parameter never reaches the log — on any path, including success, a failing exit code, a timeout, a cancellation and a failure to start.

A command pointing at an executable that cannot be found is logged as:

Failed to start command '{$MyTool}': The system cannot find the file specified.

The reason the operating system gave is preserved, and the message names the parameter to check rather than the value it produced.

Gateway-dispatched runs behave the same way — both the log file kept on the gateway machine and the lines it sends back carry the reference, not the value.

Troubleshooting¶

The package fails immediately with a "file not found" style error. The executable is not on the gateway, not on its PATH, or the path is misspelled. Use a full path to the executable.

Access denied, or the command cannot see a network share. The gateway service account lacks permission. Grant it access to the path, or run the gateway under an account that already has it.

The package reports success but the work did not happen. The tool exited 0 despite failing. Add whatever flag makes it return a real exit code (sqlcmd -b), or wrap it in a script that checks its own result.

Save is unavailable and the completion badge is below 100%. Hover Save to list what is missing. With separated settings on, all three environments need a gateway and a command.

The working directory will not save. It is limited to 120 characters — a hard column width in the database. Shorten the path, or move the script somewhere closer to the root.

A global parameter token appears literally in the log. Check the parameter exists and the token spelling matches, including case. Note that substitution is skipped for commands starting with epcmd.

Related¶

• Create a PowerShell package — for scripts that can run in Timextender Cloud without a gateway
• Execution connections
• Installing an execution connection
• PowerShell script exit code not recognized — the PowerShell-package side of the exit-code difference above