Skip to content

CLI Reference

Complete reference for the rninja command-line interface.

Synopsis

rninja [OPTIONS] [TARGETS...]

Description

rninja is a drop-in replacement for Ninja with built-in caching. It reads build.ninja files and executes build commands, using a content-addressed cache to skip redundant work.

Options

Build Control

-j, --jobs <N>

Run N jobs in parallel.

  • 0 = use all available CPU cores (default)
  • Any positive integer limits parallelism
rninja -j8      # 8 parallel jobs
rninja -j0      # all cores
rninja -j1      # sequential

-k, --keep-going <N>

Keep going until N jobs fail.

  • 1 = stop on first failure (default)
  • 0 = keep going indefinitely
  • Any positive integer sets the failure limit
rninja -k0      # never stop
rninja -k5      # stop after 5 failures

-l, --load-average <N>

Do not start new jobs if the system load average is greater than N.

rninja -l 4.0   # pause if load > 4.0

-n, --dry-run

Dry run mode. Print commands that would be executed but don't run them.

rninja -n

File Selection

-f, --file <FILE>

Specify input build file. Default is build.ninja.

rninja -f custom.ninja

-C, --dir <DIR>

Change to DIR before doing anything else.

rninja -C out/Release

Output Control

-v, --verbose

Show all command lines while building.

rninja -v

--json

Output in JSON format for machine consumption. Useful for scripts and AI agents.

rninja --json

Debugging

-d, --debug <MODE>

Enable a debugging mode. Available modes:

Mode Description
explain Explain why targets are being rebuilt
keepdepfile Don't delete depfiles after processing
stats Show execution statistics 
rninja -d explain
rninja -d stats

--trace <FILE>

Write Chrome trace output to FILE. Open with chrome://tracing.

rninja --trace build_trace.json

Subtools

-t, --tool <TOOL>

Run a subtool instead of building. See Subtools for details.

rninja -t list          # list tools
rninja -t clean         # clean outputs
rninja -t compdb        # compilation database

Daemon Control

--no-daemon

Disable daemon mode. Run in single-shot mode without connecting to or spawning a daemon.

rninja --no-daemon

--daemon-socket <PATH>

Use a custom daemon socket path.

rninja --daemon-socket /tmp/my-rninja.sock

Other Options

-w, --log <FILE>

Write build log to FILE. (Experimental)

rninja -w build.log

--version

Print version information.

rninja --version

--help

Print help information.

rninja --help

Arguments

[TARGETS...]

Targets to build. If not specified, builds the default targets defined in the build file.

rninja                  # default targets
rninja target1 target2  # specific targets
rninja all              # 'all' target if defined

Exit Codes

Code Meaning
0 Success
1 Build failed
2 Invalid arguments

Environment Variables

rninja respects these environment variables:

Variable Description
RNINJA_CACHE_ENABLED Enable/disable caching (0 or 1)
RNINJA_CACHE_DIR Cache directory location
RNINJA_CACHE_MODE Cache mode (local, remote, auto)
RNINJA_CACHE_REMOTE_SERVER Remote cache server URL
RNINJA_CACHE_TOKEN Remote cache authentication token

See Environment Variables for complete list.

Configuration Files

rninja loads configuration from these locations (in order):

  1. .rninjarc (project directory)
  2. ~/.rninjarc (home directory)
  3. ~/.config/rninja/config.toml (XDG config)

See Config Files for format details.

Examples

Basic Builds

# Build default targets
rninja

# Build specific target
rninja my_target

# Build multiple targets
rninja target1 target2

Build Configuration

# Use 4 parallel jobs
rninja -j4

# Build in different directory
rninja -C out/Release

# Use different build file
rninja -f release.ninja

Debugging

# See why targets rebuild
rninja -d explain

# Verbose output
rninja -v

# Dry run
rninja -n

# Generate trace
rninja --trace trace.json

Automation

# JSON output for scripts
rninja --json

# CI build
rninja -j0 -k0 --json

Subtools

# Clean build outputs
rninja -t clean

# Show dependencies
rninja -t deps target

# Generate compile_commands.json
rninja -t compdb > compile_commands.json

# Check cache
rninja -t cache-stats

Ninja Compatibility

rninja supports all standard Ninja flags:

Ninja Flag rninja Support
-C DIR Yes
-f FILE Yes
-j N Yes
-k N Yes
-l N Yes
-n Yes
-t TOOL Yes
-d MODE Yes
-v Yes
-w Yes (experimental)

Additional rninja Flags

These flags are rninja extensions:

Flag Description
--json Machine-readable JSON output
--trace FILE Chrome trace output
--no-daemon Disable daemon mode
--daemon-socket PATH Custom daemon socket

See Also