Using the linux terminal & ssh

Setting up klipper requires a bit of work to be done from the linux terminal. For some, this is trivial. For others, this is a completely new experience. If you’re in the second group, this guide will give you some of the basics: by no means is it comprehensive, but it will try to hit the bits you’re most likely to need to get klipper up and running

  • Linux in general uses the command line (aka, “the terminal” ) for management much more than windows or mac do. This is all the more true on our printers, where we generally don’t want the extra overhead of running a full desktop. This means that most navigation is text based: keyboard, arrow keys, etc. The mouse isn’t very involved.

  • For the most part, this guide assumes you will be connecting via ssh: a network tool which lets you securely control the linux device over the network. However, a very similar terminal can also be accessed by directly connecting a keyboard and screen. This can be very useful when, for example, dealing with a network problem that prevents you from using ssh.

Pretty much every Single Board Computer has an hdmi port. However, on some models (Notably the Pi4, and Pi0) it’s a micro-hdmi port. If you have one of these models, it’s worth taking note of this, and acquiring a suitable adapter: if you ever need it, you probably aren’t going to want to wait to acquire one.

  • ssh is a suite of tools widely used in the linux world to remotely access machines, granting terminal access, transfering files, and providing many other advanced functions. To do what we need to do here, we are barely scraping the surface of what ssh is capable of.


finding the pi

To connect to a Pi over the network, you need 3 pieces of information:

  1. Your username on the pi. You may have set this during the flashing step. If not, it likely defaulted to pi
  2. Your password: You should already know this: you set this during the flashing step.

On old Raspberry pi systems, the default password was “raspberry”. Modern installs wisely discourage this

  1. A hostname or IP Address.

Hopefully, mdns is working on your network, and you can simply use the “.local” address. If you set a hostname for your device via pi imager, the hostname will be the_thing_you_set.local if you didn’t, your device will likely be raspberrypi.local or mainsailos.local If none of these options work, you may need to locate the pi by IP address. see Finding a Device’s IP Address

ssh tools


Putty is a windows ssh client with a long history. It is a free download here.

To connect with putty:

  1. Open Putty
  2. Enter your username and hostname in the “hostname” field, in the format <user>@<host>, for example pi@mainsailos.local
  3. Press the “Open” button
  4. Since this is your first time connecting to this remote machine, you will find yourself facing security warning. It should be safe to just click accept. Putty Security Alert
  5. You will then find yourself with a black window and a password prompt. Type your password, and press enter. It is normal for nothing to appear on the screen while you are typing the password. (Linux applications traditionally hide passwords completely rather than the more familiar dots or stars) Putty password entry

mac command line

  1. Open the Mac OS “terminal” app (Utilities->Terminal)
  2. type a command in the format ssh <user>@<host>, substituting your username and hostname from your pi: for example ssh pi@mainsailos.local, and press enter.
  3. You will then be presented with a security warning regarding an unrecognised security key. It should be safe to simply accept this by typing “yes” and press enter. OpenSSH security warning
  4. You will then be prompted for your password. Type your password, and press enter. It is normal for nothing to appear on the screen while you are typing. (Linux applications traditionally hide passwords completely rather than the more familiar dots or stars)

pc command line

  1. Open the windows commandline: Press the windows key, type “cmd” and press enter
  2. type a command in the format ssh <user>@<host>, substituting your username and hostname from your pi: for example ssh pi@mainsailos.local, and press enter.
  3. You will then be presented with a security warning regarding an unrecognised security key. It should be safe to simply accept this by typing “yes” and press enter. OpenSSH security warning
  4. You will then be prompted for your password. Type your password, and press enter. It is normal for nothing to appear on the screen while you are typing. (Linux applications traditionally hide passwords completely rather than the more familiar dots or stars)

the terminal

Congratulations! If you’ve gotten here, you should have crossed the first major hurdle: you’ve gotten yourself connected to the pi. Now let’s look around a little. The basic work flow here, is that everything scrolls up the screen, so whatever is at the bottom is the most recent interaction. Consider the following screenshot: the linux command prompt

  1. We received our initial prompt shifting@voront:~ $ . This is a very information-dense prompt, but let’s not worry about it too much for now. For now, it simply tells us that the machine is ready to receive our next instruction. We then typed the command ls, and pressed enter.
  2. The pi responded with the listing of files in our current directory
  3. When the command finished, we were given a new prompt, ready for the next instruction.

the prompt


  • ls (“list”) is used to list the files and directories in a given location. By default, it shows just the name of each item in the current directory.
  • ls <some_dir_name> will list the files in the named directory, instead of the current one
  • ls -l will include additional information, including file size, and ownership
  • ls -h will convert numerical information to a more readable form. commonly combined with -l, to get file sizes in a more readable form
  • arguments can be chained together. for example ls -lh klippeer will list off all the files in the “klipper” directory, and include the extended information, with the numbers in a readable format
  • ls has many, many other options, but these couple should be enough to get started



  • cd (“change directory”) is used to change your “working directory” basically, this is the equivelent of browsing to a different folder in Windows Explorer or Mac Finder
  • cd will return you to a special location: your home directory. (more on what that means later)
  • cd <some_dir_name> will change your working directory to the named directory
  • cd .. will move up one level, into the parent directory


  1. We start out in a certain directory (“/”), and run “ls” to see what it contains
  2. Noting a directory called “home”, we decide to change into it with the cd command
  3. we land in “home”. Note how the command prompt changes to tell us where we are.

cp & mv

  • cp (“copy”) makes a duplicate of a file. cp <original_name> <new_name>
  • mv (“move”) moves a file to a new filename or a new directory mv <original_file> <new_name>
  • in both cases, the second command could be either a new file name, OR a new directory name. for example, cp 1.txt 2.txt will make a duplicate file named 2.txt`, in the current working directory. whereas mv 1.txt klipper/ would create the new copy, still called 1.txt, in the directory “klipper”.


  • nano is a simple text editor that is available on virtually every possible system. It comes in handy if you ever need to solve a problem which is preventing Mainsail/Fluidd from editing configs, or when you need to edit things outside of the limited scope that the Mainsail & Fluidd editors allow access.
  • you start the editor with nano <file>, so, for example to edit the printer.cfg, one might issue the command nano ~/printer_data/config/printer.cfg
  • once in nano, remember you still don’t have a mouse, so all navigation is by keyboard: Page up & Page down are your friends!
  • Note the list of controls across the bottom: ^ meaning the ctrl key, so, for example ctrl-o is Write Out (aka Save), and ctrl-x is Exit.
  • when you go to save, nano will always ask what file to write to: It defaults to the file you’re editing, so assuming you’re just wanting to save, just press enter.



  • sudo (superuser do) allows you to execute commands as the system administrator (known as “root”) when necessary.
  • sudo will sometimes ask for your password: note, this is the password of the normal account, not some other administrator password
  • This tool is often needed to edit a file in /etc or /boot that normal users don’t have access to. For example, several common processes require edits in the file /boot/config.txt. This file is only editable by root. so if you try to just open it normally with nano nano /boot/config.txt, you’ll just get an error: file is unwritable. Instead, you can use sudo: sudo nano /boot/config.txt, and then you’ll be able to edit normally. nope


  • more is used to page through a text file, but not edit it. This is most often useful when reviewing log files, for example more ~/printer_data/logs/klippy.log. Note that more starts at the top of the file, which, in a log is the oldest information, and as you scroll through, the info gets newer.


  • tail just shows the last bit of a file, such as the most recent few lines in a log file: tail ~/printer_data/logs/klippy.log
  • tail also has a very useful “follow” function. in this mode, it will show you the last few lines, and then wait, and show new entries as they appear: tail -f ~/printer_data/logs/klippy.log. (press ctrl-c when you’re done and want back to the command prompt)


  • Windows: both putty and windows command line support a slightly obscure form of copy/paste. Anything you highlight in the putty/cmd window automatically gets copied to the clipboard, and any time you right click, it pastes.

  • Mac: ⌘ + C / ⌘ + V should work pretty much normally

the file system

  • the filesystem is laid out a little differently than you may be familiar with on other systems. Everything is organized in to a single “tree” structure, with the top level directory simply being called / (sometimes referred to as the “root” directory). A typical / contains a handful of system folders etc, lib, boot, home, and each of those contains many further things, until you have the entire system.
graph LR;

(note, the actual filesystem typically contains many more directories, this is just a simplified example)

  • when using a command like cd, there are two different forms the directory name can take: either starting with a /, or not. When you start with a /, as in cd /tmp you are giving an absolute path, meaning that the path is expressed all the way from the / directory. this means it will function exactly the same no matter where you are coming from. By contrast, you can also do cd tmp. This is a relative path, meaning that it’s starting from the current working directory. So if we start out in /home/pi, and we do cd tmp, we’ll end up in /home/pi/tmp. but if we start out in /, and issue that same command, we’ll end up in /tmp.


  • the ~ symbol is short hand for “the user’s home directory”. generally, this will be /home/<username>, so for example, /home/pi
  • this is also the directory you first start out in when logging in.
  • on most klipper installs, this will be the directory that contains most of the klipper stuff: klipper, mainsail, moonraker, etc.

This trait of starting out in the home directory is important to remember when looking for things that are in the system root, such as /etc or /boot: you need to go up to / before you’re going to see them.

remote file transfers


  • filezilla is a simple, user friendly file transfer tool, available for pc & mac from here
  • simply fill in the host as sftp://<hostname> eg: sftp://mainsailos, the username & password, & hit “quickconnect”
  • your files on your computer appear on the left, the files on your voron on the right, and you can drag and drop between them. Note that you are a normal user here, so you will not be able to directly write files to /boot or /etc filezilla


other tips & tricks

Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the RSA key sent by the remote host is x.
Please contact your system administrator.
Add correct host key in /ua/username/.ssh/known_hosts to get rid of this message.
Offending RSA key in /ua/username/.ssh/known_hosts:5
RSA host key for mainsailos.local has changed and you have requested strict checking.
Host key verification failed.

In certain circumstances (mostly involving re-imaging your pi), you may encounter this rather intimidating message. If you don’t think anything should have changed, its worth checking that you’re actually trying to connect to the device you meant to connect to. If you know that it makes sense your pi’s ID has changed, such as the pi being a new setup, it is safe to resolve this by simply deleting the old, conflicting key off your computer.

ssh-keygen -R <hostname> will take care of this. for example, if your pi is mainsailos.local, you would do ssh-keygen -R <hostname>

Finding a device’s IP Address

  • if your pi is accessible via mainsailos.local or raspberrypi.local, don’t worry about it too much. You can (and should) just use that hostname everywhere. If you ever do need to get the ip, open a command prompt (pc) /terminal (mac) and type ping <hostname>, eg: ping mainsailos.local. this will get you the IP.
  • If you have access to your network router, you may also be able to look in it’s DHCP settings, and see what IP address your pi has been given
  • Failing the approaches above, “Angry IP Scanner” should be able to locate the pi on your network:

    • download Angry IP scanner from here
    • install & run it
    • Go to Tools->Fetchers. Select the “MAC Vendor”(1) fetcher, and press the left arrow(2) to activate it. press okay(3)


    • Go to Settings, and change to the Display(1) tab. Set Display in the results list to Alive hosts(2). press okay (3)


    • Press “Start”
    • Once the scan finishes, look for a result with a MAC Vendor similar to “Raspberry Pi Trading”


Static IPs

  • on most networks, IP addresses are handed out by DHCP: “Dynamic Host Configuration Protocol” This means the device’s IP may occasionally change. If you’re accessing the device via host name, this doesn’t matter: the hostname should follow it. But if you’re accessing it by IP directly, this is quite inconvenient.

  • There are two basic approaches to solving this problem. The better solution, where possible, is to use an “IP Reservation” feature on your DHCP server (your network router). Basically, this allows you to tell the router “whenever you see this device, always give it the same IP address. The trouble here, is that not all routers have this feature.

  • The second solution is to actually configure the Pi itself to use a static IP, removing it from the DHCP system entirely. To do this correctly involves determining an appropriate IP, and a variety of settings to use on your network, as such, it’s beyond the scope of this quick little guide. However, there are a wide variety of guides easily found.