back to index



OctoPrint is a neat software used as a web-operated printserver for 3D printers.

Sometimes, however, a commandline control is desired.

There is a utility called octocmd, that provides a way to upload and select files, run printing and slicer, and watch status. It however misses a lot of functionality.

An easy way with a richer set of commandline utilities was desired. Many functions (move, extrude, retract, pause...) may need to be run from e.g. a control panel sending USB HID events. A simple script then can handle the events and send the associated OctoPrint API calls.

Solution approach

The OctoPrint server comes with a powerful REST API accessible over the HTTP protocol and extensively using JSON format for the data. The production version API documentation is here.

The HTTP REST API can be accessed via cURL commandline utility.

The OctoControl, aka 8control, is a simple bash shell script housing multiple utilities and calling the API via cURL. The host and API key are fetched from the octocmd configuration file, housed in ~/.octocmd.conf - the file is in JSON format and is parsed via grep and cut to extract the variables.

Bash was chosen instead of e.g. Python. Octocmd is written in Python and on less powerful computers, e.g. the Raspberry Pi, Python tends have a fairly slow start. Bash scripts, at least the simple ones, are much snappier.

Command suite

The core command is a bash shell script, All the commands it hosts are linked by a symbolic link.


8control octoprint command suite, complementary to octocmd

Global commands:
  -h      this help
  -v      verbose (show requests)
  -vv     more verbose (show requests and headers)

  8checkcfg              check 8control's configuration
  8apiver                show API and server version
  8statusraw             show controller connection status, raw JSON
  8status                show controller connection status, status only
  8connect               connect controller to server
  8disconnect            disconnect controller from server
  8g "<code>"            send gcode to controller
  8gcode "<code>"        send gcode to controller
  8g1 "<coords>"         send G1 command to controller
  8start                 start loaded print job
  8print                 start loaded print job
  8restart               restart print job
  8pause_raw             pause/unpause running job, raw call
  8pause                 pause running job
  8resume                resume running job
  8cancel                cancel running job
  8xcancel               cancel running job, keep temperature setting of the tools
  8home                  home printer head
  8jog <x> <y> <z>       jog printer head by x,y,z mm
  8jog <z>               jog printer head by z mm
  8settemp <temp>        set tool0 to <temp> 'C
  8setbed <temp>         set bed to <temp> 'C
  8ex <mm>               extrude <mm> millimeters of filament (negative to retract)
  8extrude <mm>          extrude <mm> millimeters of filament (negative to retract)
  8fex <mm> [mm/min]     fast extrude <mm> millimeters of filament (negative to retract) with optional speed
  8fan <on|off|0..255>   control the head fan
  8gettemp_raw           show tool temperature
  8gettemp               show tool temperature
  8getbed                show bed temperature, raw JSON
  8getbed                show bed temperature
  8run <cmd>             run system-menu command (see .octoprint/config.yaml for commands)
  8ls_raw                list available files (raw JSON)
  8ls                    list available files
  8ll <filename>         show info for <filename> (raw JSON)
  8fselect <filename>    select <filename>
  8getjob                information about current job, raw JSON
  8msg "<msg>"           show message on display via M117 gcode
  8beep                  beep via M300 gcode


Some commands retrieve data. They are usually in JSON format. The most commonly needed data are extracted via grep. Such commands have the corresponding _raw version that shows the JSON itself.

All the commands start with 8. The host file starts with _8, to avoid collisions.

Most commands do not have parameters. Most commands do not have any response.

Some commands use G-code. There is also a command to directly send G-code commands to the printer.

Status handling

Connection handling


The G-code is converted to uppercase before being sent to the printer.

Job control

The pause API call toggles the printing and paused status; calling it twice would pause and resume the print. To achieve stateless operation, the corresponding commands are checking the printer status before acting; 8pause will fire only when Printing, 8resume only when Paused. This will be important for pausing prints when some supervisory electronics (filament jam or runout sensor, computer vision...) detects an operator-requiring anomaly.

Beware, the API documentation shows /api/job correctly but the examples show /api/control/job - this was confusing a bit.


The jog directions are sign-flipped, to match the directions of the G-code based movements, so e.g. positive Z would move up and negative would move down.


The fast extrude is handy for replacing the filament.


Head fan

System commands

The commands are set up in the ~/.octoprint/config.yaml file. Typical functions are switching the video streaming on and off.

This was not described in the documentation, or it was not possible to find there, so it had to be reverse-engineered using tcpdump or tshark.

File commands

Display and alert commands




The archive with the host file and the symlink can be unzipped right to the target directory (usually /usr/bin/ or /usr/local/bin/. Simply cd to the directory and then run tar -xzvf &lt;archive_name.tar.gz&gt;.


If you have any comments or questions about the topic, please let me know here:
Your name:
Your email:
Leave this empty!
Only spambots enter stuff here.