back to index


Solution approach
Command suite
            Status handling
            Connection handling
            Job control
            Head fan
            Speed control
            System commands
            File commands
            Display, beep, and alarm commands


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)

Config file location: /etc/octocmd.conf (or /root/.octocmd.conf) (current=/etc/octocmd.conf)
  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
  8reconnect             disconnect, reset, connect
  8g "<code>"            send gcode to controller
  8gcode "<code>"        send gcode to controller
  8g0 "<coords>"         send G0 command to controller
  8g1 "<coords>"         send G1 command to controller
  8speed <factor>        override speed, in percents
  8feed <factor>         override filament feed, in percents
  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, M104 S<temp>
  8setbed <temp>         set bed to <temp> 'C, M140 S<temp>
  8settempr <temp>       adjust tool0 by <temp> 'C, M104 R S<temp>; firmware MUST support Shad's R extension
  8setbedr <temp>        set bed to <temp> 'C, M140 R S<temp>; firmware MUST support Shad's R extension
  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
  8eject [-t temp]       eject filament, optionally heat head before
  8gmulti <cmd> [<cmd>]...  send several commands in one transaction
  8upload <file>         upload gcode file
  8runfile <file>        upload gcode file as tmp.g and execute it
  8fan <on|off|0..255>   control the head fan
  8fan2 <on|off>         control the bed fan (M42 P57)
  8gettemp_raw           show tool temperature
  8gettemp               show tool temperature
  8getbed                show bed temperature, raw JSON
  8getbed                show bed temperature
  8servo <num> <angle>   set servo angle
  8run <cmd>             run system-menu custom command (see .octoprint/config.yaml or 8ListCmds for commands)
  8reset                 run system-menu command "reset"
  8on                    power up the printer
  8off                   power down the printer
  8ListCmds              list system commands (raw JSON)
  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 [n [f]]   beep via M300 gcode [optionally for n milliseconds [at f Hz]]
  8alarm [d] <t|b> <T>   wait until <t>ip or <b>ed reaches temperature T ("d" for decreasing), then beep and exit
  8alarmq [d] <t|b> <T>  wait until <t>ip or <b>ed reaches temperature T ("d" for decreasing), then quietly exit


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

Speed control

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, beep, and alarm 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;.

Do not forget to run the script to make the symlinks, eg. to /usr/bin:

./ /usr/bin/


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.