Command Line Runner

The Command Line Runner executes one or more shell or batch commands directly on the BuildNinja agent machine. It provides a flexible way to run command-line tools, scripts, and system utilities, making it well suited for lightweight automation, tooling integration, and ad-hoc build tasks.

When to Use

Use the Command Line Runner when you need to:

• Run simple build commands such as npm, mvn, gradle, or make.
• Execute command-line tools and utilities.
• Perform short automation or one-off tasks.
• Carry out file operations or environment validation checks.
• Quickly prototype or debug build steps before formalizing them in a build configuration.

Parameters

Parameter	Description
Step Name	Optional name for the build step. Defaults to the runner name if not specified.
Working Directory	Directory where commands are executed. Defaults to the system working directory if left blank.
Commands	The shell command(s) to run during the build process.
Success Exit Code	Optional. Specifies the exit code that should be treated as a successful execution. The default success exit code is 0.
Execute Next Command	Controls whether subsequent steps continue to run if this step fails.

Typical Use Cases

Common scenarios for using the Command Line Runner include:

• Installing and updating dependencies using package managers.
• Enforcing code quality through linters and formatting tools.
• Compiling or bundling frontend assets.
• Packaging binaries, archives, or deployment artifacts.
• Running lightweight utility scripts for housekeeping or validation tasks.

Example

This example demonstrates how to install dependencies and build a Node.js application using the Command Line Runner.

Configuration settings:

• Step Name: Build Frontend

• Working Directory: /workspace/app

• Commands:

  npm install
  npm run build

• Execute Next Steps: Enabled

Limitations

• Not suitable for complex logic or long-running scripts.
• Limited support for advanced error handling and branching logic.
• Maintainability decreases as command complexity grows.
• OS-specific command syntax can reduce portability across environments.
• Provides limited reusability compared to the Script Runner or Config File Runner.

Best Practices

• Keep commands short, focused, and easy to understand.
• Avoid embedding complex conditional or looping logic in command steps.
• Use the Script Runner for multi-step workflows or advanced logic.
• Use environment variables instead of hardcoded values for better portability and security.
• Group related commands logically to improve readability and troubleshooting.