Orca Slicer CLI: The Complete Reference for Headless Slicing

Orca Slicer has a capable command-line interface that almost nobody knows about. The official documentation doesn't cover it. There are a handful of GitHub issues and Discord threads that gesture at it, but no complete reference exists. This is that reference.

Printago's cloud slicing pipeline supports both Orca Slicer and Bambu Studio — users choose their slicer engine per job. This is a deep-dive on Orca Slicer's CLI specifically. What follows is everything we've learned running over 35,000 headless slices: the complete flag reference, practical invocation patterns, and the gotchas we hit the hard way so you don't have to.

A Typical Headless Invocation

The core flags for any automated slice are --slice, --load-settings, --load-filaments, --export-3mf, and --pipe for live progress. --load-assemble-list handles multi-color or multi-object plates without a project file. A full invocation looks roughly like this:

orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament1.json;filament2.json" \
  --filament-colour "#FF0000;#0000FF" \
  --allow-newer-file \
  --min-save \
  --debug 2 \
  --pipe /tmp/sandbox/progress.pipe \
  --export-3mf /tmp/sandbox/.build-output/printago.gcode.3mf \
  input.3mf

The Complete CLI Reference

Output of orca-slicer --help on Orca Slicer 2.3.2, lightly formatted:

OrcaSlicer-2.3.2:
Usage: orca-slicer [ OPTIONS ] [ file.3mf/file.stl ... ]

Input & Configuration

Flag	Description
--datadir <path>	Load and store settings at this directory. Useful for maintaining different profiles or loading configurations from network storage.
--load-settings "setting1.json;setting2.json"	Load process and machine settings from JSON files. Semicolon-separated. Order matters: machine first, then process.
--load-filaments "filament1.json;filament2.json;..."	Load filament settings, one file per slot. Semicolon-separated.
--load-filament-ids "1,2,3,1"	Load filament IDs for each object. Maps objects to filament slots.
--load-assemble-list <assemble_list.json>	Load an object assembly list from a JSON config file. Used for multi-object plates and multi-color jobs without a project 3MF.
--load-custom-gcodes <custom_gcode_toolchange.json>	Load custom G-code from a JSON file.
--load-slicedata <directory>	Load cached slicing data from a directory. Avoids re-slicing when inputs haven't changed.
--allow-newer-file	Allow slicing a 3MF that was created with a newer version of Orca Slicer. Without this flag, newer 3MFs are rejected.
--skip-modified-gcodes	Skip modified G-code in the 3MF from printer or filament presets.
--uptodate-settings "setting1.json;setting2.json"	Load uptodate process/machine settings when using --uptodate.
--uptodate-filaments "filament1.json;filament2.json;..."	Load uptodate filament settings when using --uptodate.
--uptodate	Update config values in the 3MF to the latest.

Slicing Actions

Flag	Description
--slice <option>	Slice the plates. 0 = all plates, i = plate number i. This is the flag that triggers headless slicing.
--no-check	Skip validity checks, such as G-code path conflict detection.
--allow-mix-temp	Allow filaments with high and low temperature requirements to be printed together.
--skip-objects "3,5,10,77"	Skip specific objects by index in this print.
--mstpp <seconds>	Maximum slicing time per plate in seconds.
--mtcpp <count>	Maximum triangle count per plate for slicing.
--enable-timelapse	Mark this slicing job as using timelapse.
--normative-check	Run normative item checks.

Object Arrangement & Transformation

Flag	Description
--arrange <option>	Arrangement behavior: 0 = disable, 1 = enable, other = auto.
--allow-rotations	Allow rotation when placing objects during arrange.
--allow-multicolor-oneplate	Allow multiple colors on a single plate during arrange.
--avoid-extrusion-cali-region	Avoid the extrusion calibration region when placing objects.
--assemble	Arrange supplied models on a plate and merge them into a single model.
--ensure-on-bed	Lift objects above the bed when partially below it. Disabled by default.
--orient <option>	Orient options: 0 = disable, 1 = enable, other = auto.
--rotate <degrees>	Rotation angle around the Z axis in degrees.
--rotate-x <degrees>	Rotation angle around the X axis.
--rotate-y <degrees>	Rotation angle around the Y axis.
--scale <factor>	Scale the model by a float factor (e.g. 1.5 for 150%).
--clone-objects "1,3,1,10"	Clone objects from the load list.
--repetitions <count>	Repetition count of the whole model.
--convert-unit	Convert model units.

Output

Flag	Description
--export-3mf <filename.3mf>	Export the sliced project as a 3MF (containing G-code). This is the primary output for headless slicing.
--export-slicedata <directory>	Export slicing data to a folder for later reuse with --load-slicedata.
--export-settings <settings.json>	Export current settings to a JSON file.
--export-stl	Export objects as a single merged STL.
--export-stls	Export objects as multiple individual STLs to a directory.
--outputdir <dir>	Output directory for exported files.
--min-save	Export the 3MF with minimum file size. Recommended for production pipelines.

Progress & Debugging

Flag	Description
--pipe <pipename>	Send slicing progress as JSON to a named pipe. Each line is a JSON object with plate_index, plate_count, plate_percent, total_percent, message, and warning.
--debug <level>	Set logging level. 0=fatal, 1=error, 2=warning, 3=info, 4=debug, 5=trace.
--info	Output model information without slicing.
--help, -h	Show this help.

Metadata Embedding

Flag	Description
--metadata-name "name1;name2;..."	Metadata key list to embed in the output 3MF. Paired with --metadata-value.
--metadata-value "value1;value2;..."	Metadata value list corresponding to --metadata-name.
--makerlab-name <name>	MakerLab name to embed in the 3MF.
--makerlab-version <version>	MakerLab version to embed in the 3MF.

Downward Compatibility

Flag	Description
--downward-check	Check whether the current machine is downward compatible with the machines in the list.
--downward-settings "machine1.json;machine2.json;..."	Machine settings list to use for downward compatibility checking.

Setting Priority

Orca Slicer resolves settings in this order (highest to lowest):

1. Command-line flag values
2. Values from --load-settings and --load-filaments
3. Values embedded in the 3MF file

This means you can override 3MF-embedded settings by passing flags directly on the command line, or by loading settings files that take precedence.

---

Practical Examples

Basic headless slice — single filament

orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament.json" \
  --allow-newer-file \
  --export-3mf output.gcode.3mf \
  model.3mf

--slice 1 slices plate 1. Use --slice 0 to slice all plates. The output is a .gcode.3mf — a 3MF archive with the G-code inside, not a raw .gcode file.

Multi-filament slice — three slots

orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament_pla_red.json;filament_pla_white.json;filament_pla_blue.json" \
  --filament-colour "#FF0000;#FFFFFF;#0000FF" \
  --allow-newer-file \
  --export-3mf output.gcode.3mf \
  model.3mf

Filament files and colors are both semicolon-separated, positionally matched. Slot 1 gets filament_pla_red.json with color #FF0000, slot 2 gets white, slot 3 gets blue.

Multi-object plate without a project 3MF

When you want to arrange multiple STL files onto a single plate without first creating a project file, use --load-assemble-list:

# assemble-list.json
{
  "plates": [{
    "plate_index": 1,
    "plate_name": "plate_1",
    "need_arrange": true,
    "objects": [
      { "path": "/tmp/1.stl", "count": 1, "filaments": [1], "assemble_index": [1] },
      { "path": "/tmp/2.stl", "count": 1, "filaments": [2], "assemble_index": [1] }
    ]
  }]
}

orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament1.json;filament2.json" \
  --load-assemble-list assemble-list.json \
  --allow-newer-file \
  --export-3mf output.gcode.3mf

Assemble list field reference:

Top level is an object with a plates array. Each plate has:

Field	Type	Required	Description
plate_name	string	Yes	Plate identifier (e.g. "plate_1").
need_arrange	bool	Yes	true = let the slicer auto-arrange objects. false = use explicit pos_x/pos_y positions.
objects	array	Yes	List of object entries for this plate.
plate_params	object	No	Key-value string map of plate-level setting overrides.

Each object entry:

Field	Type	Required	Description
path	string	Yes	Absolute path to the STL or 3MF file.
count	int	Yes	Number of copies to place. Must be ≥ 1.
filaments	int[]	Yes	1-based filament slot indices. Must be length 1 (applied to all copies) or equal to count (one per copy).
assemble_index	int[]	No	When multiple objects share the same assemble_index value, they are merged into a single composed model. Used to build multi-part objects from separate STL files.
pos_x	float[]	No	X position(s) in mm. Length 1 or equal to count. Only used when need_arrange: false.
pos_y	float[]	No	Y position(s) in mm. Same rules as pos_x.
pos_z	float[]	No	Z offset(s) in mm.
subtype	string	No	Volume type. Default is "ModelPart". Other values: "NegativeVolume", "ParameterModifier".
print_params	object	No	Key-value string map of per-object setting overrides (e.g. {"support_type": "normal(auto)"}).
height_ranges	array	No	Array of {min_z, max_z, range_params} objects for height-range setting overrides.

The need_arrange: true lets Orca Slicer place objects automatically. Use false with explicit pos_x/pos_y when position matters — for example, placing a label at a specific location on a base part.

Streaming progress via named pipe

The --pipe flag sends slicing progress as newline-delimited JSON to a named pipe. This is how you get real-time feedback from a headless slice.

# Create the named pipe
mkfifo /tmp/progress.pipe

# Read from it in the background
cat /tmp/progress.pipe | while IFS= read -r line; do
  echo "Progress: $line"
done &

# Run the slicer
orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament.json" \
  --pipe /tmp/progress.pipe \
  --export-3mf output.gcode.3mf \
  model.3mf

# Clean up
rm /tmp/progress.pipe

Each line written to the pipe is a JSON object:

{
  "plate_index": 0,
  "plate_count": 1,
  "plate_percent": 47.3,
  "total_percent": 47.3,
  "message": "Generating supports",
  "warning": null
}

In practice, Printago throttles these messages at 2-second intervals and forwards them to MQTT for the dashboard to display.

Slicing without arrangement

When your input file already has objects positioned exactly where you want them:

orca-slicer \
  --slice 1 \
  --arrange 0 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament.json" \
  --export-3mf output.gcode.3mf \
  positioned-model.3mf

Profile override from command line

Because command-line values take the highest priority, you can override any setting without modifying your profile files:

orca-slicer \
  --slice 1 \
  --load-settings "machine.json;process.json" \
  --load-filaments "filament.json" \
  --layer-height 0.1 \
  --export-3mf fine-detail.gcode.3mf \
  model.3mf

Any Orca Slicer setting key can be passed directly as a flag. The full list of valid keys is in Orca Slicer's source under src/libslic3r/PrintConfig.cpp.

---

Gotchas

These are the issues we hit running the CLI in production.

printer_model must match your machine settings

If the printer_model in your 3MF's Metadata/project_settings.config doesn't match the printer_model in your machine settings JSON, slicing will either fail or produce incorrect output. When routing a print job to a different printer model than the one originally used to set up the project, you need to patch the 3MF's printer_model before slicing.

The output is a .gcode.3mf, not a .gcode

--export-3mf produces a 3MF archive that contains the sliced G-code at Metadata/plate_1.gcode (or plate_N.gcode for multi-plate jobs). It is not a raw G-code file. If your downstream tooling expects .gcode, you need to extract it from the archive first. Most Bambu printers accept the .gcode.3mf directly and prefer it over raw G-code because it includes thumbnails and metadata.

Temp files accumulate fast — always clean up

Each slice invocation writes to a working directory: the input files, settings JSONs, the named pipe, intermediate outputs, and the final .gcode.3mf. On a model of any complexity, this can easily be 200-500MB per job. On a machine running continuous production slicing, this accumulates to disk exhaustion within hours if you don't clean up.

Always delete the working directory after each slice, whether or not it succeeded:

# Shell
rm -rf /tmp/sandbox-id/

# Node.js
fs.rmSync(sandboxPath, { recursive: true, force: true });

Wrap cleanup in a finally block so it runs even on slicing errors or timeouts.

9.5-minute timeout is a hard ceiling

Orca Slicer's CLI does not have a built-in timeout. If you're running it as part of an automated pipeline, set your own. A reasonable ceiling for production use is 9-10 minutes — models that take longer than that are almost certainly pathological (extremely high triangle count, overly complex support structures, or the slicer is stuck). Printago kills the process with SIGTERM at 9.5 minutes.

---

What's in the Output 3MF

The .gcode.3mf that --export-3mf produces is a standard ZIP archive. Inside:

Metadata/
  plate_1.gcode          # The sliced G-code
  plate_1.png            # Plate thumbnail (requires OpenGL — blank in headless mode)
  slice_info.config      # JSON with filament usage, time estimates, layer count
  project_settings.config # The resolved settings used for slicing
  model_settings.config  # Object placement and metadata
3D/
  3dmodel.model          # The geometry

slice_info.config is particularly useful. It contains filament usage in mm and grams per slot, estimated print time, and layer count — all the data you need for cost estimation and production tracking without parsing G-code.

---

This is a living document. Orca Slicer's CLI changes between versions and new flags appear without announcement. If you're building on top of this, pin your Orca Slicer version and run --help after each upgrade to catch additions or removals.

If you're running a print farm and don't want to build this slicing infrastructure yourself, Printago handles all of it — profile management, cloud slicing, job routing, and real-time progress — so you can focus on production instead of plumbing.