CLI Commands Reference

Complete reference for all GScript command-line tools.

Command Overview

bash

gscriptc <command> [options] <file>

Available commands:

compile - Compile GScript to G-code
validate - Validate GScript syntax and semantics
simulate - Simulate G-code execution
estimate - Estimate machining time and costs
parse - Parse and inspect GScript AST/IR
machines - List available machine profiles

compile

Compile GScript programs to machine-ready G-code.

Usage

bash

gscriptc compile <file> --target <backend> [options]

Required Options

--target <backend>, -t <backend> - Target CNC backend

Available backends:

grbl - GRBL controller (most common CNC machines)
marlin - Marlin firmware (3D printers with CNC capability)
fanuc - Fanuc CNC controller (industrial machines)
linuxcnc - LinuxCNC/EMC2 controller
tinyg - TinyG controller (compact motion control)
gcode - Generic G-code (basic compatibility)

Optional Flags

-O<level> - Optimization level (0-3)
- O0 - No optimization (fastest compile, debugging)
- O1 - Basic optimization (default, redundancy elimination)
- O2 - Standard optimization (arc fitting, feed smoothing) [planned]
- O3 - Aggressive optimization (path reordering) [planned]
--profile <name> - Use machine profile for validation and limits
-o <file>, --output <file> - Write output to file (default: stdout)
--no-post-process - Disable post-processing

Examples

Basic compilation:

bash

gscriptc compile program.gscript --target grbl

Save to file:

bash

gscriptc compile program.gscript --target grbl -o output.gcode

With optimization:

bash

gscriptc compile program.gscript --target grbl -O2

Using machine profile:

bash

gscriptc compile program.gscript --target grbl --profile cnc-3018

Multiple backends:

bash

gscriptc compile program.gscript --target grbl -o grbl.gcode
gscriptc compile program.gscript --target fanuc -o fanuc.gcode

Output Format

Generated G-code includes:

Header comments with part metadata
Unit and positioning setup
Tool changes with spindle control
Toolpath G-code commands
Safe retracts and program end

Example output:

gcode

; Part: mounting-plate
; Material: aluminum-6061
; Generated by GScript

G21 ; Millimeters
G90 ; Absolute positioning

M6 T1 ; Tool change: drill-5mm
S5000 M3 ; Spindle on

; Operation: drill
G0 Z5.0
G0 X10 Y10
G1 Z-8.0 F300
G0 Z5.0

M5 ; Spindle off
M30 ; Program end

Optimization Details

O0 - No Optimization

Fastest compilation
Useful for debugging
Outputs raw G-code

O1 - Basic Optimization (default)

Eliminates redundant consecutive moves
Merges compatible linear moves
Reduces file size by ~15-25%
Safe for all programs

O2 - Standard Optimization [planned]

All O1 optimizations
Arc fitting for curved paths
Feed rate smoothing
Typical 30-40% size reduction

O3 - Aggressive Optimization [planned]

All O2 optimizations
Path reordering for efficiency
Advanced arc fitting
Maximum optimization

validate

Validate GScript programs for syntax and semantic errors.

Usage

bash

gscriptc validate <file> [options]

Optional Flags

--profile <name> - Validate against machine profile limits
--strict - Enable stricter validation rules

Examples

Basic validation:

bash

gscriptc validate program.gscript

With machine profile:

bash

gscriptc validate program.gscript --profile cnc-3018

What Gets Validated

Syntax Checks:

YAML structure correctness
Required blocks present (meta, tooling, setup, program, export)
Field name spelling

Semantic Checks:

Tool references exist in tooling block
Operation parameters are complete
Numeric values are valid ranges
Coordinates are within stock bounds

Profile-Aware Checks (with --profile):

Positions within machine axis limits
Feed rates within machine capabilities
Spindle speeds within machine limits
Tool sizes compatible with machine

Output Examples

Success:

Validating: program.gscript
✓ Validation passed

Syntax Error:

Validating: program.gscript
✗ Validation failed:
Validation failed with 2 error(s):
  1. Missing required metadata: part_name
  2. Tool reference 'unknown-tool' not found in tooling block

Profile-Aware Error:

Validating: program.gscript
✗ Validation failed:
Validation failed with 1 error(s):
  1. Position out of bounds in operation 0: X axis
     Machine: CNC 3018
     X Limits: 0 to 300 mm
     Requested: 350 mm

simulate

Simulate G-code execution to verify motion and detect errors.

Usage

bash

gscriptc simulate <gcode-file> [options]

Optional Flags

--summary - Display simulation summary
--machine <profile> - Use machine profile for limits
-o <file>, --output <file> - Export motion trace JSON

Examples

Basic simulation:

bash

gscriptc simulate output.gcode --summary

With machine profile:

bash

gscriptc simulate output.gcode --machine cnc-3018 --summary

Export motion trace:

bash

gscriptc simulate output.gcode -o motion-trace.json

Summary Output

━━━ Simulation Summary ━━━
✓ Commands executed: 342
✓ Motion segments: 156
✓ Total distance: 1,247.832 mm
✓ Execution time: 127.45 seconds (2.12 min)
✓ Final position: X=50.000, Y=50.000, Z=5.000
✓ Bounding box: 100.000 × 80.000 × 7.000 mm

✓ No errors
━━━━━━━━━━━━━━━━━━━━━━━━━

Motion Trace Format

The exported JSON contains detailed motion data:

json

{
  "segments": [
    {
      "segment_type": "rapid",
      "start": {"x": 0.0, "y": 0.0, "z": 0.0},
      "end": {"x": 10.0, "y": 10.0, "z": 5.0},
      "feed_rate": 5000.0,
      "duration": 0.17,
      "distance": 14.14
    },
    {
      "segment_type": "linear",
      "start": {"x": 10.0, "y": 10.0, "z": 5.0},
      "end": {"x": 10.0, "y": 10.0, "z": -2.0},
      "feed_rate": 300.0,
      "duration": 1.4,
      "distance": 7.0
    }
  ],
  "summary": {
    "total_time": 127.45,
    "total_distance": 1247.832,
    "bounding_box": {
      "min": {"x": 0.0, "y": 0.0, "z": -8.0},
      "max": {"x": 100.0, "y": 80.0, "z": 5.0}
    }
  }
}

Use this with visualization tools to preview toolpaths.

Error Detection

Simulation catches:

Out-of-bounds moves
Machine limit violations
Invalid G-code commands
Feed rate issues
Unexpected tool positions

estimate

Estimate machining time and costs for a program.

Usage

bash

gscriptc estimate <file> [options]

Optional Flags

--profile <name> - Use machine profile for accurate estimates
--rate <cost> - Hourly machine rate (for cost calculation)
-o <file>, --output <file> - Export estimate as JSON

Examples

Basic estimate:

bash

gscriptc estimate program.gscript

With cost calculation:

bash

gscriptc estimate program.gscript --rate 50

Export to JSON:

bash

gscriptc estimate program.gscript -o estimate.json

Output

━━━ Machining Estimate ━━━
Cycle time: 2.12 minutes
  Rapid moves: 0.35 min (17%)
  Cutting: 1.77 min (83%)

Material removal: 2,400 mm³
Tool usage:
  drill-5mm: 4 operations, 0.4 min
  endmill-6mm: 1 operation, 1.72 min

Estimated cost (@ $50/hr): $1.77
━━━━━━━━━━━━━━━━━━━━━━━━━

parse

Parse GScript and output AST or IR for inspection.

Usage

bash

gscriptc parse <file> [options]

Optional Flags

--ast - Output Abstract Syntax Tree
--ir - Output Intermediate Representation (default)
--pretty - Pretty-print JSON output

Examples

View IR:

bash

gscriptc parse program.gscript

View AST:

bash

gscriptc parse program.gscript --ast

Pretty-printed:

bash

gscriptc parse program.gscript --pretty

Use Cases

Debugging parser issues
Understanding program structure
Building tooling on top of GScript
IDE/LSP development

machines

List available machine profiles.

Usage

bash

gscriptc machines

Output

Available machine profiles:
  - cnc-3018     GRBL 3018 CNC Router
  - cnc-3040     GRBL 3040 CNC Router
  - custom       Load from JSON file

Use with --profile flag:
  gscriptc compile program.gscript --profile cnc-3018

Global Options

Available for all commands:

--help, -h - Show help information
--version, -V - Show version information
--verbose, -v - Enable verbose output
--quiet, -q - Suppress non-error output

Examples

bash

gscriptc --version
gscriptc compile --help
gscriptc validate program.gscript --verbose

Common Workflows

Development Workflow

bash

# 1. Validate while writing
gscriptc validate program.gscript

# 2. Compile when ready
gscriptc compile program.gscript --target grbl -o output.gcode

# 3. Simulate before running
gscriptc simulate output.gcode --summary

# 4. Estimate time
gscriptc estimate program.gscript

Production Workflow

bash

# Validate with profile
gscriptc validate program.gscript --profile cnc-3018

# Compile with optimization
gscriptc compile program.gscript --target grbl -O1 --profile cnc-3018 -o output.gcode

# Final simulation check
gscriptc simulate output.gcode --machine cnc-3018 --summary

Multi-Backend Workflow

bash

# Generate for multiple machines
for backend in grbl marlin fanuc; do
  gscriptc compile program.gscript --target $backend -o output-$backend.gcode
done

Exit Codes

0 - Success
1 - Validation error
2 - Compilation error
3 - Simulation error
4 - File not found
5 - Invalid arguments

Next Steps

Machine Profiles - Configure machine-specific settings
Hooks System - Automate workflows with hooks
Language Reference - GScript syntax guide
Examples - Working program examples

CLI Commands Reference ​

Command Overview ​

compile ​

Usage ​

Required Options ​

Optional Flags ​

Examples ​

Output Format ​

Optimization Details ​

validate ​

Usage ​

Optional Flags ​

Examples ​

What Gets Validated ​

Output Examples ​

simulate ​

Usage ​

Optional Flags ​

Examples ​

Summary Output ​

Motion Trace Format ​

Error Detection ​

estimate ​

Usage ​

Optional Flags ​

Examples ​

Output ​

parse ​

Usage ​

Optional Flags ​

Examples ​

Use Cases ​

machines ​

Usage ​

Output ​

Global Options ​

Examples ​

Common Workflows ​

Development Workflow ​

Production Workflow ​

Multi-Backend Workflow ​

Exit Codes ​

Next Steps ​

CLI Commands Reference

Command Overview

compile

Usage

Required Options

Optional Flags

Examples

Output Format

Optimization Details

validate

Usage

Optional Flags

Examples

What Gets Validated

Output Examples

simulate

Usage

Optional Flags

Examples

Summary Output

Motion Trace Format

Error Detection

estimate

Usage

Optional Flags

Examples

Output

parse

Usage

Optional Flags

Examples

Use Cases

machines

Usage

Output

Global Options

Examples

Common Workflows

Development Workflow

Production Workflow

Multi-Backend Workflow

Exit Codes

Next Steps