Structure of Commands

Running a Command

Commands are in the format below where command is the name of a command, parameter_1, parameter_2 and parameter_3 are parameters or arguments passed to the command command parameter_1 parameter_2 parameter_3

• All commands are executed in the current folder
• Commands can take any number of parameters 0 or more which change their behaviour
  Examples:
  • ls lists the current folder the command is ls
  • ls /home lists the /home directory the command is ls again but this time we also have a parameter /home, Many commands will take a path or file as a parameter to instruct the command which item to work from.
    Parameters can also modify command behaviour.
  • ls -l the command is ls but we give an argument -l in this case ls will list extra details
  • ls /dev/serial/by-id/* This is a fairly common command during initial setup for a klipper machine, the command is ls and the parameter is /dev/serial/by-id/*. /dev/serial/by-id/* is a special directory on the linux file system which contains a file for each serial device connected with a name reflecting what the operating system calls it see Block Devices
• Parameters may also be refered to arguments or switches. Switch is normally used for parameters of the form -x or –help which change the command behaviour

Escaping a Running command

In the event you open a command which doesn’t close itself (or runs for a long time) the command can be instructed to stop with the keyboard combination ctrl + c

Case Sensitivity

All linux commands and folder names are case sensitive, this means that file, File and FiLe are all different files and could be in the same directory, as this is for obvious reasons confusing people avoid names like this. This is of note because whilst ls will list the files in the current directory LS or Ls will result in a command not found error.

Tab Completion

Whilst using the terminal it is possible to ask for your current command or command part to be finished for you. This is helpful with say long file names where you can type the first two or three letters and then press tab to complete the full name, if there are multiple options hitting tab twice will list all of them. This does not work with all commands but does work with almost all file commands and service commands.

Sudo

The sudo command is a powerful utility command which is used to perform tasks with elevated permissions, roughly analogous to run as administrator functionality on windows. sudo does not do anything directly but instead runs the command in its parameters under the “root” user, the top level administrator account for a linux machine. Typically the sudo command is needed when installing or updating tools, changing configuration files for the operating system or controlling services.

Example

Running whoami will return your username Running sudo whoami will return the username root as the command has been run as the root user.

Command Chaining

Many commands in guides will chain commands, this is the process of writing a single line which executes multiple commands. Most of these depend on the “return value” of the commands as they execute, the finer points of what these means is beyond this guide, for our purposes each command reports if it succeeded or failed and the joins can check this there are multiple ways to do this but the most common are below

Examples

cd ~ && git clone https://github.com/dw-0/kiauh.git run the command cd ~ and if that is successful then run the command git clone https://github.com/dw-0/kiauh.git

Finding Help

Help Parameters

Most commands supply a help option usually this is --help or -h as a parameter e.g. ls --help

Man Command

man is the manual command, man is a command which accesses documentation for other commands, these manual pages can be very verbose and technical but likely include all the detail you could need if doing something unusual Example

• man ls this will launch the manual tool pointed at the entry for the ls command

Finding your way around the file system

Assuming you have found your way into a terminal via ssh or the device itself the following commands should help with moving between folders or identifying where you are
included here are also the comands for moving, copying and renaming files

Magic symbols

Commands

common usage

cd .. move up one folder i.e. from /home/me to /home
cd ~/klipper move to the folder called klipper in the users home directory, frequently this is where klipper is installed by most people
mv out/klipper.bin out/firmware.bin rename the generated firmware image from klipper.bin to firmware.bin, here the comand is assumed to be running from ~/klipper as this is where the firmware build commands normally run from

Git

Git is a version control system, these are likely unfamiliar terms but for most of our usage this means that the git command can be used to make a copy of a folder from a git repository (like the one klipper is held in https://github.com/Klipper3d/klipper) or update the files in a repository we previously copied. The tool will track files it is made aware of and allow for copies of the “repository” or collection of files to be made and for any changes to be kept in sync, this is how updates made through mainsail or fluid work in the background.
Git is a complex tool and can produce errors or issues which will need different resolutions, this is rare when using commands such as clone or creating an initial installation.
A “cheat sheet” for many git commands is available at https://training.github.com/downloads/github-git-cheat-sheet/ and full details are available online. One good resource for further reading is https://glasskube.dev/guides/git/. Full usage of git is outside of the scope of this documentation.

The git command works like other commands documented above although the first parameter passed to git is normally an instruction for the type of action to be undertaken.
In the next few sections we explore a few commonly used git commands

git clone

This command is used to get a copy of a repository held in git a in the current working folder, most commonly this is used to get klipper(https://github.com/Klipper3d/klipper) or KIAUH (https://github.com/dw-0/kiauh) during an initial installation.

Example command

git clone https://github.com/dw-0/kiauh.git This command breaks down into three parts, git the command we want to run clone the operation we want to perform and https://github.com/dw-0/kiauh.git this tells git clone where to get the files it should clone. This will create a folder with the repository name kiauh (the last bit after / and before .git) in the current working directory. Additional parameters can be passed to the clone command to tweak its behaviour, these are rarely needed in our use case.

git pull

This command must be run inside a directory which git created (usually in our case through a git clone command). It will update the local files in the folder to match the latest version it was cloned from.

Example command

git pull This command breaks down as run git with an instruction to pull the latest version of the parent repository. git will then check for changes between your local files and the parent and try to update the files, in the event there is a conflict (a file modified differently both locally and in the parent repository) git will attempt to resolve the issue or if this fail will ask you what to do. It is rate for klipper users to directly perform this operation and it is more typically invoked via one of the klipper web interfaces like Fluid or Mainsail.

Installing tools (apt-get)

The apt and apt-get commands allow for tools and their dependencies to be installed and maintained by the operating system. This can be considered to be a little like an app store in how it behaves apt and apt-get are two different interfaces to the same tooling, apt is the more modern version but frequently apt-get os called for in example commands. we will document apt-get here for this reason. all commands in this section will require “admin” permissions to run successfully, this is done by starting the command with the sudo, super user do command see sudo

apt-get works like other commands documented above although the first parameter passed to apt-get is normally an instruction for the type of action to be undertaken.

apt-get update

The command apt-get update will update the locally stored index of what tools are available and at what version, it does not make any changes to the installed files

apt-get upgrade

The command apt-get upgrade will update the tools installed and tracked by apt-get (including most of the pre-installed applications) to the latest version in the local database (see apt-get update ) This command will note upgrade code operating system features

apt-get dist-upgrade

The command apt-get dist-upgrade is much like the apt-get upgrade command but it will also update the underlying core operating system files

apt-get install

The command apt-get install is used to install a new tool or library. install accepts a -y switch which will make it automatically answer yes to questions to the user. The most frequent question posed by this tool is “installing this tool will require 30MB of disk space, continue?” so it is frequently added in installation guides.

examples

apt vs apt-get

apt is the replacement for apt-get, for install/remove/upgrade commands the user visible behaviour is the same, there are some subtleties to what is going on inside the black box. AWS have a good write up on the finer details https://aws.amazon.com/compare/the-difference-between-apt-and-apt-get/. It is expected for the foreseeable further both will be available.

Commands which end in .sh

These are not strictly commands but are instead scripts, scripts are a series of commands which automate tasks for you, commonly tools which we install from git such as Kiauh or Klipper itself provide scripts to simplify initial setup. Commonly these commands will have the form ./toolname/script.sh this is running a script called script.sh which is located in a folder called toolname under the current working folder.

Example

Below we have an example of a sequence from the Kiauh install script First move to the home directory (~) and then git is used to get Kiauh into the folder kiauh cd ~ && git clone https://github.com/dw-0/kiauh.git And then run a script that is in that folder ./kiauh/kiauh.sh This runs the script by starting in the current folder . then folder kiauh then a script called kiauh.sh, this assumes that the user is still in the directory ~ from the cd command above A common error to see with script launch commands is to try and launch the command whilst in the wrong directory, look carefully at any instructions for any cd commands.

Where is my hardware

Block Devices

The linux operating system maps all hardware devices are files, this may seem a little odd if you are used to how windows handles devices, it is not necessary to understand why this is the case or the advantages or disadvantages here. This affords some advantages in our use case. The underlying hardware handling on modern linux distribution is performed by a tool called udev. This uses a series of rules to create device files on the disk. All very confusing and “technical” but for us this means that a printer connected by a usb port will appear in the directory /dev/serial/by-id/ and look like a file. We can therefore use the ls command to look for printers, due to the magic of udev these will even frequently have helpful names including klipper or marlin in the device names. This is helpful to us as these names remain attached to a single serial device, particuatly with usb serial devices the ports can be renamed in their “raw” form of /dev/usbTTY0, /dev/usbTTY1 and simlar depending on the order in which they are detected.

Useful Commands

Services

Like all operating systems linux uses background services to provide functionality which runs at boot up. In common use with klipper instalations there are a handful of services which we might interact with. On most modern linux discributions, including all common klipper host options services are managed through systemd. The finer details of what all of this means and how it works is not too important however commands come up for starting and stopping services so these are recorded below Most control of the services are done through the systemctl command

Why?

These commands are not used in normal operation but can be helpful if a machine is not starting properly or during firmware flashing. A common use case is to stop the klipper service so that a firmware update tool can talk to the serial port used by the control board during an mcu firmware update.

General Structure

systemctl commands are generally structured as systemctl instruction service where

Instructions

This is an incomplete list of instructions for systemd and only aims to cover the main options in common use.

Service Names

Example Systemd Commands