Docs menu: Introduction

Docs › Command line

Command line

nativecam-cli runs the same engine as the app, without the UI. Use it to script exports, check G-code in CI, simulate files from other CAM programs, and convert controller settings and tool libraries.

Building and running

The CLI is part of the NativeCAM repository and needs the same tools as the app: an Apple-silicon Mac on macOS 14 or later, with the Swift 6 toolchain (the Xcode Command Line Tools are enough). From the repository folder, run any command through SwiftPM:

$ swift run -c release nativecam-cli demo demo.nativecam
Wrote demo.nativecam

The first run builds it. Always pass -c release: the geometry and simulation are far slower in a debug build.

To run it from anywhere, build it once and copy the binary somewhere on your PATH:

$ swift build -c release --product nativecam-cli
$ cp .build/release/nativecam-cli ~/bin/

The examples in these pages call it nativecam-cli. Rebuild it after you git pull, or it keeps the old engine.

Commands

CommandWhat it does
demo, demo3d, newWrite the demo sign, the 3D relief demo or an empty project
postGenerate a project's toolpaths, write the file for its machine, and check it against the controller and the toolpaths. Also air cuts and setup sheets.
simSimulate material removal for a project or a G-code or ShopBot file, print what was removed and the job time, and optionally write an image or heightmap
acceptanceWrite the acceptance test program for a controller
machineRead speeds, accelerations and travel from a controller's settings, and optionally apply them to a project
toolsRead a Fusion 360, Vectric or NativeCAM tool library and optionally save it as a NativeCAM library

Run nativecam-cli with no arguments for a one-line usage summary. It exits with status 0.

Arguments

  • The command comes first, then its input file, then options: nativecam-cli post job.nativecam -o job.tap.
  • Options take one value, separated by a space (--cell 0.5, not --cell=0.5). Quote paths with spaces.
  • Options a command doesn't know are ignored without a warning, so check spelling.
  • Lengths given on the command line are in millimetres unless a page says otherwise. post --air-cut is in the G-code's own units.

Output files

  • Commands that write G-code take -o as a stem: its extension is replaced with the controller's (.tap for Mach4, .nc for Grbl, .ngc for LinuxCNC, .cnc for Centroid, .sbp for ShopBot, and so on).
  • Without -o, post writes next to the project, with the project's name.
  • A controller that can't stop for a tool change gets one file per tool, named name 1 of 2 - T5.nc, name 2 of 2 - T1.nc, and so on. An air cut adds (air cut) to the name.
  • Existing files are overwritten without asking.

Messages

Findings print one per line, tagged with their severity, the same checks the app shows:

[info] Cut out sign: Cuts through the material (0.0200 in into the spoilboard).
[warning] G-code: Line 14: Whether M6 stops for the tool change depends on the program sending the file. Make sure yours pauses on M6. (2 more lines like this.)
[error] 1 rapid move(s) cut through material

Lines from the job checks start with the toolpath's name; lines from the checks on the posted file start with G-code. Lengths in messages use the project's display units.

Exit status

StatusMeaning
0The command finished. Warnings and info lines don't change this, and neither does sim's report of rapids through material.
1Something stopped it: a missing argument, an unknown command, a file it couldn't read or write, a controller NativeCAM has no post for, or (for post) G-code that failed its checks. The reason goes to standard error, and the output file isn't written.
$ nativecam-cli post
usage: nativecam-cli post <project.nativecam> [-o out.tap] [--air-cut height] [--sheet out.html] [--force]
# exit status 1

Same caveats as the app. The CLI writes exactly what the app's Export would. Only Avid Mach4 output has run on a real machine; for any other controller, run the acceptance test first, and air-cut every new program.