Ellane learns the command line

Install some (Homebrew) packages

2024-07-06T07:58:28Z

Ellane

Done. I was held up briefly because there was no visual feedback when typing my password; got it on the second try.

It seems to have worked, as brew help is showing me a list of ways to get started. I'll be (wisely) leaving those alone until you help me learn what they're all about.

So the purpose of Homebrew is just to install hledger. How might we do that?

Homebrew's web site is amazing so we might as well double-check. Head over there and search for hledger using the box at the top. You should find yourself on the formulae page for the app.

We don't really need to know how Homebrew works. Just like we don't really know what's happening when we launch an installer and next, next, next. But, just briefly, it has what it calls 'formulae', which are just installation scripts. And sometimes you have to add a 'cask' (they really push this metaphor) so that you can access these formulae.

But in this case, the page tells us exactly what we need to do:

brew install hledger

Which is a familiar pattern by now: some command, brew, followed by some options. Let's keep reinforcing this with a quick trip to man brew, which tells us that the syntax for brew is:

brew command [--verbose|-v] [options] [formula]

Let's drop our command in below that.

brew command [--verbose|-v] [options] [formula] # man brew
brew install                           hledger  # our command

So that's:

brew, the main command.
install, which is brew's 'command': you're saying, brew, please install a thing.
- Similarly you can brew remove ....
Optionally the flags --verbose or -v -- a very common flag that tells the command to be verbose in its output.
- You tend to use this when you're trying to troubleshoot something.
- We didn't specify them in our command. You can if you like.
[options], some optional options.
- Which we're not using.
[formula], which we're specifying as hledger.

All of this is just to get these patterns deeper in your brain. The more familiar they are the more comfortable you'll be.

`hledger` #

Assuming there were no errors -- and you should always read the last few lines of the installation output just to be sure -- you've now got hledger installed. Run it!

hledger

So when I ran it I thought two things:

Oh that looks cool!
It's flashing a cursor ... does it want me to run a command?

Homework #

Now that this is installed, see what you can do with it. I've played myself and it is pretty arcane! So don't worry if you don't get too far.

(You can't mess this up. If the worst happens, we just remove it and add it again.)

Homebrew

2024-07-01T07:42:16Z

Okay, let's turn in the direction of hledger. We're going to install it.

First, we need to install Homebrew. But first: what is it?

Package managers #

We're all used to installing software, and keeping that software up to date.

You might use the App Store, which is one-click with invisible updates in the background.

You might download a .pkg file, which you double-click and next, next, next your way through. The application it installs then prompts you, over time, to perform updates.

But how do you install and keep updated applications for your Terminal? There are a bunch of ways, but Homebrew has become the de-facto standard for the Mac. Because it's just really nice.

Other `hledger` options #

It's worth nothing that there are other installation options for hledger.

But given how nice Homebrew is, we're going to use it.

Install Homebrew #

Okay, right there on the home page. Simply copy paste this command in to Terminal.

🚨 🛑 ‼️ 🚨 🛑 ‼️ #

A massive word of caution. Whenever someone, including me, tells you to 'simply copy/paste a command in to Terminal': don't do that.

By now you have an idea of what this thing can do. It's a window in to the deepest parts of your system. And so entering random commands from the internet is a massive, massive risk.

So what do we do? Well, we just have to be aware of that, and to trust Homebrew. Because, realistically, we can't validate this command ourselves. It's too hard. So unless Homebrew has been hacked, or the people running it suddenly sold out, we'll be okay.

Just be aware of the risk.

The installation command #

We don't need to understand it, but let's deconstruct it a little just so you're aware.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

`/bin/bash -c` #

This is an absolute path to a command: actually, to the bash shell itself. Then the flag -c says to 'read the next command from a string'.

So this just says, 'do the rest of this command in a shell'. And we're already in a shell.

I'm not sure why this is required, to be honest. I think it's just the Homebrew people being really, really safe: you should be able to run this command from darned-near anywhere and it'll work.

`"$( ... )"` #

The command to be passed to bash -c is enclosed in quotes and dollars and brackets for reasons. ;-)

`curl` 🟢 #

This is what's doing all of the work.

curl gets web pages. Try it out: curl https://jdcm.al will dump the HTML of my home page in your Terminal.

I'm not sure what the c is for, but url as in, a URL.

The flags -fsSL presumably do important things in this context, which man curl would explain to us, but I'm not going to go there.

So what is curl getting? This:

https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh

And that's just a URL! So we can view it in a browser.

It's ... long ... and ... really complicated. But what we're looking at here is the installation script for Homebrew. I barely understand it.

Now if we zoom back out and look at the whole installation command, we've got:

bash -c running something that
curl -fsSL downloads, which is
this script.

It should be obvious why this is risky from a security perspective.

Caution to the wind #

It's time, though. Copy the command from the Homebrew home page, paste it in your Terminal, and off you go.

When the installation finishes, it'll tell you to do something like:

- Run these two commands in your terminal to add Homebrew to your PATH:
    (echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/john/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"
- Run brew help to get started
- Further documentation:
    https://docs.brew.sh

Yours will be subtly different to mine, so copy them from your screen, not this page. But just so it's clear, the two commands are:

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/john/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

...and then brew help to check it's worked. If it hasn't, closing and re-opening your Terminal window might help.

That's enough for today, and I need to go and cook dinner!

A rapid advance

2024-07-01T07:33:31Z

Just copy/pasting this one from Mastodon. I'm a bit behind, sorry everyone! –j.

Okay, terribly late on this one, and I still haven’t written a proper post for our little site. But I figure if I just type this at the kitchen table rather than agonising over perfection, that’s probably better.

(I will update the site later.)

So we’re going to ‘pivot’, as we say in the tech industry. I set out to teach you ‘the CLI’, but that’s a massive undertaking, and your actual goal is to ‘learn plain text accounting, specifically hledger’.

Rather than possibly useless theory, therefore, we’re going to focus on the goal, and cover topics as required on our way to that goal.

In your latest blog post you mentioned that you can read stuff, but you can’t yet edit. So let’s do that now.

Now, this qualifies as a ‘potentially dangerous’ command. Because if you edit the wrong file, you could mess something up! So just make sure you’re in the right place, and maybe create some test files to start.

The command 🥁 is 🥁

pico

That’s it. You can just type pico and it’ll open.

And I’m going to leave you there. Because if you look around, I think you’ll work it out. The hints are all on-screen: see the bar along the bottom.

This is a pretty rudimentary text editor. It’s not the legendary vim. But it’s easy to use, and it’ll do the job.

And think about this: once this is all set up, there’s no reason to use the CLI to edit your plain text files. They’re just plain text files.

You can use whatever you like to edit them. And just dive down to the CLI as required.

But still, I think this is a valuable exercise. So have a play with pico, create a few files, edit a few files, and let me know how you get on.

Next, we’re going to go straight for the hledger installation page. 😬

Ellane responds... #

Challenge accepted! You’re right about not needing to use the CLI to edit my files; it’s just a vehicle for learning a skill. A mountain to climb, not to build a house on.

I’m looking forward to the next bit! I messed around with installing hLedger last year, but never understood what I was doing, or how to update to the latest version.

Later that day... #

Ahah— a challenge for both of us! I've followed your instructions to the best of my ability, and am stuck.

"You can just type pico and it will open".

What will open? I managed to use Terminal to create a new file in the location of my choice, but not to open an existing file. If I type less I can read the file, but not edit it.

This is the kind of roadblock that would have made me give up in the past—but not now! I'll keep trying to work it out.

Johnny... #

Okay, we have two possibilities here.

Just like with any other text editor, you can either:

Open it ‘empty’, and start typing a new document, or
Open it with an existing document.

It never hurts to have a look at the first line of the man page, man pico:

pico [ options ] [ file ]

So:

pico, then
some optional [options], then
optionally, a [file].

Ignoring the optional options, this gives us two paths... which might sound familiar?…

Ellane... #

I did it! Pico is more familiar with its ⌃T commands, but you've introduced me to j and k for moving around, and so I've been spoiled with single letter commands!

So… I jumped off the cliff into vim land. And I like it! With :q! under my belt I'm having fun learning how to navigate a doc.

Johnny... #

Ha! What! This is excellent.

There are many, many fine vim tutorials out there. And really once you’ve got the hang of it, ten commands gets you by.

Next stop: Homebrew. 🚏 Give me a day or so. We’re heading to the National Library to work today, it’s our happy focus place.

Lots of feedback

2024-06-08T06:21:39Z

This one has taken me a while to work through, lots to take in.

Firstly, why yes, I do happen to have a plain text file or two handy! And I note that .md seems to fall under the .txt umbrella. Nice.

Johnny

Good spotting! And in fact the CLI doesn't give a hoot about those file extensions. It's what's in the file that counts. You can call it myfile.sausages and as long as it's actually text, and not sausages, it'll open just fine.

These exercises began with the frustration of it taking me what felt like an age to navigate to a folder with text files long enough to work with. Autocomplete didn't seem to be working so I reviewed the lesson on that topic. Great! Clear on that at last.

Until I mistakenly pressed tab to summon auto complete with one quote mark at the beginning of a word—it's obvious I should have omitted it, but now I've got [dquote> and I don't know what to do with it. None of the commands I've learned thus far helped (including logout, q) so I closed the window with the red corner dot and opened a new one.

Johnny
I do that all the time! It thinks you want to split that text over multiple lines -- because you've opened a quote, but you haven't closed it yet.

The easiest way out of this and many other pickles is to hit control-C. This (usually) tells the current process to gracefully quit.

I'll tell you more about this later but for now that'll be useful to know.

Bookmarks? Shortcuts? #

Is there a way to create a bookmark, a shortcut, to get to a deeply nested folder? Please say yes!

Johnny
Yes. I've added that to the list of stuff to get to. For now, a neat trick is that you can drag a macOS folder icon in to Terminal and it'll appear as a file path.

So type cd␣, find the folder you want in Finder, and drag it on to the window.

(Note the ␣ there that we use to represent 'a space character' where it might not otherwise be so obvious.)

Using the home-row keys #

j and k are much more convenient than searching out the up and down arrow keys.

q for quit? It was really that simple?? Good to know. I've been stuck on pages like this in the past, not knowing how to get out.

If spacebar moves down one full page, is there a command to move back up one full page? EDIT: Forget this one—I found it.

Wrap at word breaks? #

I'm seeing character wrapping rather than word wrapping. Is there anything in the Settings to fix this? It disrupts the flow of reading.

Johnny
Interesting ... less doesn't do that itself, no. I'm surprised.

But! This gives me a lovely example to use in the next lesson. Watch this space.

Capitalisation of things #

Righteo, that h brings up shortcuts in the file viewer. Is this a file viewer, or a File Viewer? In my mind the former would be built-in, a CLI system-wide way of navigating a file, whereas the latter would be one flavour, like an app.

Johnny
Well in this specific case, we're in less. Which is just a file viewer. Unless I misunderstood the question?

Is Control-E the same as Control-e? When I see an upper case letter in a CLI context it feels like pressing Shift is implied. So would Control-E actually be Control+Shift+E, or is it case insensitive? Like Command-S on the Mac, for Save.

Johnny
This niggles me too, but I guess it's an old convention. I think -- if any readers have more history, let's have it -- that it's because control-shift-<character> just isn't really a thing in CLI-world. It's control-<character> or nothing, so the fact that it's indicated as E is just a style thing?

But this is just me speculating. Short answer: not case-sensitive.

Touch typing #

Yes, I touch type. 85 wpm on a good day. (It's such an important skill in my book that I stooped to bribery, offering each of my children a modest cash prize if they could demonstrate it to my satisfaction. All four did, and now as adults they are proficient where many of their peers are not.)

Johnny
I totally agree. I taught myself when I was at uni. The reasons were not noble: I was giving myself a headache copying my mate's work, looking from the screen to his work to the keyboard.

So I taught myself and it's one of the best things I've ever done. (They kicked me out of uni.)

Searching and navigating #

I pressed / to search for this string "F.." in my text file by escaping the two periods. So far so good, but what I wanted was to be taken to the first instance, and then to the next when I was ready, etc. Searching like this highlighted the right pattern, but I had to scroll through a very long document to find each instance.

Johnny
g will take you to the top of the document, then n will take you to the next instance.

I just typed this: "Why doesn't autocomplete work with the less command? Do I really have to type out the full name of the file I want to view?" before realising I'd been pressing return after the first part of the name, rather than tab.

Until this becomes (new) muscle memory, I can see I'm going to have to slow down and compare what I've learned with what my fingers are used to doing.

So. Auto complete worked when searching for a text file to open, but it returned no such file or directory until I added the file extension to the name. What's that all about?

Johnny
This should work. Perhaps there were two documents with the same name but different file extensions? Your tab-completion will only take you as far as it can before it hits ambiguity. So did it stop before the extension, but you didn't notice, so when you hit return you didn't actually have the file extension in there?

As you noted above, yeah, this is a world where you really do need to check everything. Because the CLI will do exactly what you tell it to, and no more.

I'm mentally framing this quote: "None of it is difficult; it's just unfamiliar."

A year or so ago I spent a week interacting with my .md notes exclusively in TextEdit (plain text mode), just for the experience. Those raw visuals were a good introduction for becoming familiar with the command line, I now realise.

`man man` #

Wowza, that's a lot of reading! I scanned through the man page for man itself, and for less. I can see why it's built in; that's a lot to remember. Nothing I'm not used to, though. I'm a big keyboard shortcut user in the apps I spend the most time in.

The "Convention: indicating flags and arguments" section of this lesson feels like deep water. If you've never used any of those options to man, chances are high I never will either.

Johnny
Yeah don't stress about that -- or the volume of information in many other man pages. I showed you that just to drill home the paths-and-options-and-arguments thing, as it's so fundamental.

Honestly 90% of man pages I open, skim for the tiny thing I need, and quit. They can be inscrutable and scary.

I'll leave it here, and spend the next few days playing around with man (oh gosh, the dad jokes around this one must be plentiful!).

Less is more

2024-06-06T08:41:38Z

Great questions, and we'll get to drwxr-xr-x really soon.

For now, addressing the ls-F error, let's introduce you to the built-in help pages: known as man pages.

The reason the instruction from the page at ss64 didn't work is because that page is out of date.

So how do you view up-to-date information? Well let's start with how you view any information.

Do you have a plain text file handy? #

Typing this at my kitchen table I thought, I'll have to tell her to create a plain text file that she can use to test this next bit. Most people don't just have a bunch of plain text files knocking about.

Then I remembered who I was talking to.

Let's view a file #

Emphasis on view: we have no desire to edit it.

This gets to one of the general principles in the CLI: the principle of least privilege.^[1] If you don't need to edit a file, don't open it in a file editor: open it in a file viewer.

The oldest command, and the one you'll see referenced most often, is more. Unfortunately that's another one that's in my muscle-memory. Because there's a better command, and as you're new you might as well start using it.

In classic Unix style, it's called less.^[2]

We'll use less, but if you see more in online instructions you can either use it, or substitute less.

`less` 🟢 #

cd yourself to a folder that has some text files.^[3] And then, as you might expect:

less yourfile

It'll show the file #

Big whoop! What's more interesting is how we move around the file, because you should assume that your mouse won't work. (It will probably scroll up and down for you. But don't do that.)

Again, there are well-worn conventions that will serve you in many CLI situations.

The space key will move you down one full page. This is a really nice way to read a long article.
Arrow-up and arrow-down will move you up and down a line.
- But the more CLI way to do it is to use j and k.
- These keys are on the home row. Your fingers are already there.
- And they're the same keys that vim uses, so learning them now will be really handy later.
q quits.

There are tons more, and there's no point me listing them all: press h to bring up the help screen.

`^` means the `control` key #

Another convention, and this one's universal. ^E means control-E.

Search is interesting #

If you hit /, you're in search mode. Type a word, hit return.

To find the next instance of the same search, hit n. The previous, N.

Again, this is how vim works.

When you get used to these shortcuts -- j, k, / to search -- you start to move around a lot more quickly.

(Just curious: do you touch-type?)

Homework: read all of the `less` help #

The help page has a lot of nerdy terminology that ties together everything we've learned so far. It might look scary to start, but just read it all slowly, try out the various options, and get used to how it all looks.

Being able to see a screen like this and absorb it all is the superpower we're aiming for. None of it's difficult; it's just unfamiliar.

Make sure you're really comfortable with that before we move on

`man` pages #

So this brings us to the man page, one of the wonders of the modern world.

Every (well-behaved) command has its own manual page. It tells you everything you need to know about that command: its flags, options, and the arguments that it takes.

So man is the command, and it takes flags, options, and arg... well, let's just have a look.

man man

You're looking at the man page for man. :-)

Convention: indicating flags and arguments #

Let's dissect this first line.

man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]
         [-m arch[:machine]] [-p [eprtv]] [mansect] page ...

This is telling us that:

The command is man.
It optionally accepts a d h and o, or any combination thereof, as flags.
It optionally takes either t or w as flags. But not both.
- The pipe symbol | means 'or'. One or the other.
- Or, because they're both in [square brackets], neither!
It optionally takes M as an option with a required manpath argument.
It optionally takes P as an option with a required pager argument.
It optionally takes S as an option with a required mansect argument.
It optionally takes m as an option with a required arch argument, and optionally you can specify arch:machine. Options-in-options!
It optionally takes p as an option with any combination of eprtv as additional arguments.
It optionally takes a mansect argument.
It requires a page argument.
You can supply multiple arguments, denoted by ....

There's a lot there, and I've never used any of those options to man. The point of this was just to decipher that stuff at the top.

So when we did man man, we typed the command, man, and supplied the only required argument, page, which just so happened to also be man!

Keep reading #

I wonder what -a does. I can either scroll down with space, or the smarter way is to search for it with / then -a and return.

The first search result shows us this line that we're reading. Hit n for the next result, and there we go.

-a   Display all manual pages instead of just
     the first found for each page argument.

Now, we still don't really care what this actually does. The lesson here is manoeuvring around the viewer, not understanding all of man's options.

`man` is `less` #

Because man uses less. You can prove this by hitting h to bring up the help.

`BUILTIN(1)` #

There's a small idiosyncrasy if you man cd. You'll see the man page for BUILTIN(1).

This is because cd isn't considered its own program: it's so core to everything, it's built-in to the shell. To see these man pages, type man zshbuiltins.^[4]

Now you can view anything #

Check the man pages for stuff we've already seen. Now you can see that man ls doesn't have that weird ls-F thing going on.

Get comfortable with this and we'll move on. Start browsing and searching some of your own plain text files using less.

A better writer would have had this in mind when they titled this post. ↩︎
Apparently there's an even better version called most, but a) we don't need it, and b) it's not installed by default. ↩︎
If you're following along at home and you don't have a plain text file handy, you can launch less --help and use the help file to practice navigation. ↩︎
This one is obviously specific to the more modern zsh vs. bash. ↩︎

drwxr-xr-x

2024-06-06T08:38:54Z

Interesting podcast excerpt, thanks. It's good to know about Macs having a different approach to case than other systems. Seems to me if we're going to err, it should be on the side of precision—so I'll play it safe by treating everything as case sensitive from now on.

Thanks for explaining the ttys000. I figured it wasn't something I needed to know, but having that confirmed saves me from the distraction of wondering what it is every time I see it.

Just to check, I opened another window and yep, it said ttys001.

I played with ls -la for different locations on my hard drive, and the --color=always one, too. The latter produced mostly one colour, with splashes of another here and there. I suppose we'll get to the logic behind that later, if it's important enough to discuss.

When displaying ls -la there's a column on the left with information like drwxr-xr-x@ that I don't understand.

As with the colour, we'll either get to that later or it'll turn out to be something else I don't need to worry about.

Referring to the ls information at ss64.com/mac/ls.html, I tried ls-F as a shorter way of writing ls -F, but it returned an error: zsh: command not found: ls-F.

Okay. Commands, flags and options, arguments, in that order. Got it.

Flags and options

2024-06-06T00:35:58Z

We almost understand the syntax of a command. To recap, we've met the command, and its (often optional) arguments.

Now let's meet flags and options, which are two sides of the same coin.

Behaviour modifiers #

Flags modify the behaviour of a command. Let's try one out.

ls -l

That's a dash/hyphen, then a lowercase letter 'ell'.

Try the un-flagged ls and then ls -l and compare the output. The flagged variant gives you a longer output; more detailed.

The l stands for long. We've said to ls please exercise your ability to give us a longer output.

Let's try another.

ls -a

There's more stuff here: depending on your system you might see .DS_store, .localized, and look carefully: our friends . and .. are now shown.

By default, some system-level stuff is hidden from a basic ls. But a is short for all: you're asking ls to show you all the things.

Combining flags #

You can ask ls for both things.

ls -l -a

Note the order doesn't matter. But that's clunky. Dash-l, dash-a. It'd be nicer if we could combine them...

ls -la

This pattern -- ls -la -- is so common that many people make it their default. We'll see how to do that later. I just type it instinctively, it's seared in to my muscle-memory.

You can still specify an argument(s) #

Let's combine everything we know.

ls -la ~/Downloads

If that doesn't make you want to clean up that folder, nothing will.

(We'll go in to more detail about what ls -l is showing you later.)

Conventions #

There are well-held conventions that are used here. They aren't hard rules -- developers can and do break them -- but if you use them as a guide you won't go far wrong.

The command always comes first. That is a hard rule.

Then flags come next. A convention, very widely held. I can't think of an example where it isn't the case.

Then lastly, the arguments.

  ls -la ~/Desktop
`# │   │  └─ argument(s)`
`# │   └──── flag(s)`
`# └──────── command`

Flags-as-words #

-l isn't very expressive, and there are only 26 letters of the alphabet. So full-word flags are also totally normal.

And here's a well-held convention that I do see broken: full-word flags should start with two dashes.^[1]

ls --color=always

...and this is now an option #

I just realised that we've moved from a flag to an option. Do you know why?

Flags are either there or not. On or off. I imagine the analogy is to a raised flag: up, or down.

Options have more data. What's with =always? Well, the other options are =auto or =none.

You can think of this as an argument to the option. We'll see a lot more of this as we go on so don't worry too much about this for now.

All together now #

As you might imagine, you can mash all of this together.

ls -la --color=always ~/Downloads

Everything is just a variety of this #

First the command.

Then all of the flags and options.

And finally any arguments.

That's the basic structure of every command.

Homework #

The man page for ls is online here.

Try a bunch more options and see what you can get ls to produce. Soon, I'll show you how to bring these man(ual) pages up directly in Terminal.

Looking at you, Apple. ↩︎

Case-sensitivity, ttys, and the prompt

2024-06-05T23:41:53Z

Case-sensitivity #

Ellane
Question: is case important?

I didn't know you could do that thing with cd desktop. I find that a little weird and surprising.

Traditionally, *nix systems are case-sensitive.

Your Mac is not. It could be, but it isn't. There was a really good discussion on ATP recently: check episode 583 at 1:12:10.

Pretend like it is and you won't go far wrong.

`ttys` #

Ellane
One more question: what's ttys000?

When Terminals were the whole computer, they each had an ID. Just like your computer has a name.

When you launch a new Terminal window, it gets an identifier in the same way. Because you can launch another Terminal window, and be running commands in each.

Your system needs to know which command belongs to which window. So that's what ttys000 is.

Fun fact: ttys is short for teletyper secure. There's a great history lesson here -- this stuff goes back centuries.

We'll talk about this more later.

The prompt #

Ellane
And why the % sign? I seem to remember a $ sign being there last time.

This is just a style thing.

Until recently, the language that you were using in your Terminal was bash. The default 'prompt' for bash is $.

A couple of macOS versions ago they switched to zsh, which is more modern. Its default prompt is %.

The sh part of both of those is short for 'shell'. The original shell was just called sh! Wikipedia has a nice overview.

We won't use any zsh-specific stuff in this tutorial. And unless they say otherwise, all of the commands you'll find online that tell you how to install a thing will work in both shells.

A question of case

2024-06-04T07:45:26Z

I successfully cdd to "A_folder_in_quotes" by typing cd \"A and then pressing <tab>.

Then I navigated to a folder with word spaces inside my Obsidian vault, which is nestled four folders deep (don't judge), and pressed <tab> to auto complete its name, which is ALL THE NOTES.

Terminal completed the string like this: cd ALL\ THE\ NOTES.

If I was typing it I'd have initially thought to put the backslash close to the next word, but now I can see that it's immediately preceding the word space, which is the thing we need to escape.

`this\that` #

I tried to cd to the this/that folder two ways: cd this\/that didn't work (and I don't know why), while cd "this/that" did.

Johnny: Look at this one more closely!

It should be this\that — the same backslash that you use for the escape character.

The puzzle is: how do you include the escape character in an argument if it's the escape character?

Classic error! Okay, I've named the folder correctly now. The answer is, you use two of them: cd this\\that

Is case important? #

Question: is case important? It doesn't seem to be. I've noticed that cd Desktop returns ellane@macbook-pro Desktop % , while cd desktop returns ellane@macbook-pro desktop %.

It's the same location each time, so I'll assume location names aren't case sensitive unless you tell me otherwise.

What's a tty? #

One more question: what's ttys000? And why the % sign? I seem to remember a $ sign being there last time.

Last login: Mon Jun 3 13:29:54 on ttys000
ellane@macbook-pro ~ %

It's good to learn the why behind things that look different to my GUI-trained eyes.

I used to view things like slashes that went the wrong way and underscores between words as tech-virtue signalling: We're More Technical and Clever Than You So We Wrap Things In Extra Bits Because We Can. Seems silly now!

Escape arguments, completely

2024-06-03T20:59:57Z

Let's use these annoying spaces to go a little deeper on the concept of arguments.

We've already met them. We have a command which is optionally followed by an argument.

cd ~/Desktop
`# └─┬─────┘`
`#   the argument`

Command: cd
Argument: ~/Desktop

Arguments are sometimes called parameters. If the command is the thing that does a thing, the argument is the thing it does it to.

cd to where?

ls which folder?

So far we've seen zero- and one-argument commands. But many commands can take multiple arguments; many commands need multiple arguments.

Think about copying a file: you have to know which file to copy and then where to copy it to.

Two arguments. And we separate them by ... you guessed it ... a space.

ls will accept more than one argument. Just give it more than one folder to list.

ls ~/Desktop ~/Downloads
`# └─┬─────┘ └─┬───────┘`
`#   first     second`

Command: ls
First argument: ~/Desktop
Second argument: ~/Downloads

So now it should be obvious why trying to list out a folder with a space in its name doesn't work. The CLI doesn't know that it's one folder: actually, you gave it two arguments, and neither is the name of a folder!

How to 'escape' this problem #

This is obviously a very common issue. The solution is a technique called escaping.

When we escape a character, we're telling the CLI: treat the next character as exactly what it is.

So if it's a space, just be a space. Don't be the boundary between two arguments.

The escape character in your CLI's language is \. Put a backslash before any character to 'escape it'.

`#   one argument`
`# ┌─┴───────────────────┐`
cd My\ great\ folder\ name
`#   ^      ^       ^`
`#  escape characters`

Not just spaces #

Create a folder on your Desktop called "A_folder_in_quotes" and see if you can cd to it.

You'll need to escape those double-quote characters.

cd ~/Desktop/\"A_folder_in_quotes\"
`#           ^                   ^`
`#           the escape characters`

It's ugly. You never get used to it; you just have to learn to live with it.

Remember, any character #

It's worth reinforcing that this works before any character. Not just special characters.

So in our continuing series of it-works-but-you'd-never-actually-do-it, this is perfectly valid.

cd ~/\D\e\s\k\t\o\p

You're saying 'be a D!', 'be an e!', 'be an s!' ... but that's what they were anyway. So nothing changes.

Tab completion saves the day #

You'll drive yourself mad -- and get it wrong very, very often -- if you try to manually escape your file paths. Fortunately, there's an easier way.

The CLI will auto-complete a file path for you if you press the tab key. I'll denote that as <tab> in these code blocks.

cd ~/A<tab>

There's only one folder in my home folder that starts A, and it's Applications. Hitting tab autocompletes it for me.

Note that it doesn't press return for you. It doesn't run the command: you might have more to type before you're ready for that.

Multiple results #

On this Mac, I've got five folders in my home folder that start with D: Databases, Desktop, Documents, Downloads, and dev.

So try that:

cd ~/D<tab>

Your CLI will show you the possibilities. Now you can do two things.

Type some more characters to disambiguate your intent, and hit tab again.
Mash the tab key and watch it cycle through all the options for you. Stop when it reaches the one you want.

Pretty cool!^[1]

What's this got to do with spaces? #

Try tab completion on a folder with a space in it and find out. :-)

Homework #

1. `"A folder in quotes"` #

Make sure you can cd in to "A folder in quotes". Note the spaces in this version.

You might have to escape something yourself to get started, but as soon as you can you should use tab completion to finish the job.

2. `this\that` #

Using Finder, create a folder on your Desktop called this\that.

Now, without using tab completion, try to cd to it.

3. Too much escaping #

Earlier, we saw that this worked.

cd ~/\D\e\s\k\t\o\p

But this does not work. Why?

cd \~/\D\e\s\k\t\o\p
`# ^ extra escape character here`

For extra nerd points think about how easy this might make navigating a Johnny.Decimal hierarchy... ↩︎

It does not like spaces

2024-06-03T06:39:02Z

I’ve managed to change directory to pretty much everywhere, which is cool! Got a bit carried away trying to see the contents of a folder quite deep in multiple subfolders, and saw a zsh: permission denied message.

This was puzzling until I realised I’d forgotten to preface the path with a command!

Something else I’ve noticed is that the CLI does not like word spaces. It returns a too many arguments message any time I try to access a folder with a multiple-word name.

Is there any way around that, or do I have to rename_everything_to_remove_word_spaces?

Rather than renaming, I looked for paths with locations that were one word only and was able to ls the contents of the parent folder of the directory I was looking at.

So far so good.

File paths

2024-06-01T06:34:46Z

You stumbled in to a meme! What are the odds.

We'll come back to vim, which it turns out you can also launch by typing view (I had no idea!), much later.

But for now, yes, that's a valuable lesson. There are many situations where guessing a thing is a good idea. The CLI is not one of them.

(I might ask you to guess things, like cd Documents, where I'm pretty sure you're not going to accidentally wipe your hard drive.)

`cd`'ing to a nested folder #

File paths are core to this whole experience: many things you do involve a file, or being in a specific folder before you take an action. So let's go a bit deeper.

We'll need a subfolder, which it sounds like you have. But to keep this example simple I'm going to get you to create one on your Desktop; then people following along at home can use the same commands.

So, using the Mac Finder, create a folder called TestFolder on your Desktop. Note the lack of a space between the words.

The `/` forward slash #

This is the long way around:

cd `# takes you home if you're not already there`
cd Desktop
cd TestFolder

That # takes you home... bit in grey is a comment. Don't type that bit, including the first backtick. I'll use these to add comments to specific lines, or to show you what output to expect.

Or you can do it in a single step by using the / forward-slash, which separates subfolders.

cd
cd Desktop/TestFolder

Your prompt should update, and pwd will show you where you are.

Specify 'my home folder' #

We know that Desktop is in our home folder. But we might not be there already, so we have that annoying first cd to take us there.

We can skip this by using the shortcut for my home folder which is ~.

cd ~/Desktop/TestFolder

This is a common shortcut that you'll see in online instructions. It's handy because the person writing doesn't need to know where your home folder is: ~ is universal. Keep an eye out for it.

`.` and `..` also have special meaning #

A single . in a file path means the folder that I'm currently in.

So this works. It's not useful here, but later we'll see where we do use this.

cd ~/Desktop
cd ./TestFolder
pwd `# /Users/ellane/Desktop/TestFolder`

Two periods .. means the parent folder. You use this one all the time.

cd ~/Desktop/TestFolder
cd ..
pwd `# /Users/ellane/Desktop`

This works everywhere #

You can use all of these wherever you'd type a file path; it's not just a cd thing.

So you can ls ~/Downloads/some/other/folder.

You can combine all of this #

This crazy thing works. You'd never do it, but it works.

ls ~/../john/Desktop/TestFolder/../../././Downloads
`# lists the chaos of my Downloads folder`

Note that my username is john. Substitute for yours: if you're not sure what it is, whoami 🟢 will show it. In these lessons I assume it's ellane.

Make sure you understand why this works. Make some of your own crazy file paths just for practice.

Relative vs. absolute paths #

File paths can be relative or they can be absolute.

If they're relative, they're relative to where you are. This is what we've seen so far.

cd
cd Desktop `# relative to your current location`

These are usually shorter and more convenient. But they can go wrong: someone might assume you're in folder A, and tell you to issue some instruction that includes a relative file path.

But if you're actually in folder B, the results are unpredictable.

So we can specify absolute file paths that work regardless of where you are. We've already seen one.

cd ~/Desktop
pwd `# /Users/ellane/Desktop`

pwd always reports an absolute file path.

`/Users/ellane/Desktop` #

Let's look at this in detail.

The first thing to note is that it starts with a forward-slash. This is another special character: at the beginning of a file path, it means the top of my file system.

Try this.

ls /

Seem familiar? Before you move on, see if you can find this same location in a Finder window.

You're looking at a listing of what we call the root of your file system.

In Finder, it's what you see if you open the Macintosh HD view.^[1] Or from your home folder, you can Command-up arrow twice.

In Finder, Command-up arrow takes you up to the parent folder. So if you compare this view to /Users/ellane -- the absolute path to your home folder -- it should make sense.

The first Command-up arrow is like typing cd .., and takes you to /Users.
The second does the same again, and takes you to /. The root of your file system.

Absolute paths basically always start with a /. I'm sure there's an exception, but if you have that in mind, you won't go far wrong.

That slash says, regardless of where you are, go back to the top. It's very powerful.

Keep playing #

Of course all of this is interlinked.

cd /Users/./ellane/../ellane/Desktop/TestFolder/..

Again, absurd, but you get the idea.

The `shared` user #

Note that there's another user on your Mac whose home folder is at /Users/Shared if you want to play around with more paths.

This is an exact science #

Pay attention to how you see file paths written online. You will never, ever see someone specify Users/Shared. Because that's a relative path.

If your current directory just happens to be / then that's valid. But it probably isn't. So it'll always be specified as /Users/Shared.

Get super comfortable with this #

Simple enough concepts but you need to know these backwards. Just have a good play around and let me know if you find anything interesting.

Assuming you haven't renamed your drive. ↩︎

The One Where Ellane Launches Vim

2024-06-01T00:33:10Z

Okay, this feels like progress!

I cd'd myself to the Documents folder on the first go, by typing in cd Documents, and used ls to see the list of items in that folder. Did the same with the Downloads folder, and was reminded (again) that I really need to clear that one out.

I tried a number of things to cd to a specific nested folder, with no luck.

One of my attempts had an alarming result:

When I could see the folder I wanted to ls in the ls of its parent folder, I typed view [name of folder].

I should have known better than to experiment with unknown commands!

That gave me a blank page with a 1 at the top, and the word Insert at the bottom. logout didn't work, so I committed the press-the-red-dot-to-close-the-window sin.

No more jumping ahead of the teacher for me!

The structure of a command

2024-05-31T06:03:06Z

Feedback on homework #

Regarding closing the window vs. typing logout, not only does it feel like getting out before putting the car in 'park', it feels like opening the door and jumping out while the car is moving!

Now, this isn't what actually happens. When you close the Terminal window, it sends a signal to the CLI, and if something important is happening you'll be warned about it. It's like how modern cars lock the doors when you start moving: it makes it difficult (but not impossible) to jump out as you're hurtling down the motorway.

I think Gordon hit the spirit of it. When you're in the CLI, that's where your control is; that's where you should be issuing commands.

This is a Windows (as in Microsoft) vs. Unix mindset. Windows people think in the GUI. Unix people think in the CLI. When you're doing this stuff, put your CLI hat on.

We'll come back to this passing-around-of-signals in the future.

Tech support question #

For those of you following along at home, Ellane's Terminal window is responsive again. I tooted her a video of 'normal behaviour', which is exactly what you'd expect: after each command, you can type the next command.

We're not sure what was going on there, so we'll keep an eye on it.

The structure of a command #

Let's get to the good stuff.

Commands are all structured in the same way. They all follow one of a few patterns. When you learn those patterns, you learn the syntax of all commands.

We know that pie lunch cook isn't a valid sentence, even if we're not a chef.

And soon you'll immediately recognise that --food pie &meal lunch cook couldn't ever be a valid command: it just doesn't look right.

cook --meal lunch pie, however: while that isn't a valid command, it could be.

The first thing is always the command #

The command is the thing that decides what happens. Are you moving, copying, deleting, listing, installing, or printing a thing? It doesn't matter: but it comes first.

And sometimes that's all there is. We've already seen this: printenv. That was it. That was the command.

Let's introduce a few that we'll actually use.

Command traffic lights 🚦 #

When I introduce a new command, I'll always give it a traffic light:

🟢 Totally safe. There is nothing you could possibly do that could cause harm.
🟡 Usually safe. You can cause harm, but it's really unlikely.
🔴 Possibility of harm. I'll tell you how not to, and you probably won't, but you could.

Reference page #

I'll also create a short entry for each command on the new reference page.

These will be brief, as every command has its own documentation. We'll see that later.

New command: `cd` 🟢 #

Many -- most? -- commands are abbreviations of the thing that they do.

The shorter the command, the older it likely is. cd stands for change directory and it's older than me.

You can use it with no arguments. I'll introduce and define these soon. But for now, just type it.

cd

You should be underwhelmed! Nothing happened? But actually something did.

For one, you didn't get an error. Try garbage -- lksjdfl -- and see what happens.

Always pay attention to the output of a command. Never just assume that it worked. If it didn't work, it'll always tell you.

New command: `ls` 🟢 #

Try this one.

ls

This is short for list directory contents. And look at the results: seem familiar?

Pause here until you know exactly what you're looking at.

Guess this next bit #

So we're looking at the contents of your home folder. That's where a Terminal window opens to, by default.

Let's change directory. Try to guess how to move in to your Documents folder. Type it in.

cd Documents

Again, it doesn't look like much happened. But notice two things: first, your prompt has changed. It now has the word Documents before the %.

Second, if you try ls again, you'll see the contents of your Documents folder.

Change directory. List the contents. Change directory. List the contents.

This is something you do all the time.

Arguments #

You just saw your first argument: Documents was an argument to the cd command.

We'll go in to this in detail later, I just wanted to briefly note it here.

New command: `pwd` 🟢 #

This one stands for print working directory. Try it and see what you get.

You cd'd to your Documents folder, so it should say something like

/Users/ellane/Documents

So you know where you are because your prompt gives you a clue, and if you want to be totally certain, you pwd.

This syntax, with the forward slashes, is very specific. I'll explain it soon.

How to get home #

changing directory to your home folder is such a common task, there's a shortcut for it.

We've already seen it. Care to guess?

cd

cd with no arguments takes you home.

Take yourself on a trip 🚗 #

Use these commands a bunch until you're really comfortable with them. See where you can go. And see where you can't go.

You might have some questions about how you move around. Let me know. If not, we'll keep going.

How to close the Terminal window on 'shell' exit

2024-05-31T03:27:44Z

Homework assignment part 1 #

Figure out how to make it so that when you type logout, the window closes.

I poked around in Settings, and found an option under Shell called When the shell exits. The default behaviour was Don’t close the window, which was just the clue I needed!

As I’d hoped, Close the window was also an option in the drop down list.

Homework assignment part 2 #

Why doesn’t Johnny like closing the window with the red button?

I couldn’t find a clear answer to this, so here’s my best guess: Using the red button might run the risk of closing the window before a process has completed successfully, leading to problems.

Is it like leaving the car in a gear other than Park before turning it off?

A tech support question #

This lesson also brought up one of the frustrations I’ve faced in the past when trying to use Terminal.

I’ve pasted in the string I was given (in this case, printenv), pressed Enter, and a process completed successfully. I then wanted to do something else, but nothing I typed showed up on the screen, even though there was a blinking cursor.

What am I missing? Surely the answer isn’t to close the window and open a new one, is it, but if so, why?

Let me show you around your new car

2024-05-30T02:55:39Z

Oh good analogy! That's going to be helpful.

Learning 'the command line' is like learning how to drive. But before we can drive, we need a vehicle.

Let me show you around your new car.

Before we start, to save me some typing let's introduce a shortcut for 'the command line': CLI.

It stands for command-line interface. I'll use it from now on.

Terminal #

You can't drive without a car. The car is the framework that gives you the ability to drive: it has a chassis, four wheels, seats, air conditioning, and they come in a variety of models which you pick according to your needs.

In the same way, you need some sort of application to use the CLI. We call these 'terminals', and your Mac comes with one. Conveniently, it's called Terminal.

History lesson #

Terminals used to be the whole computer. The only thing it did was to be a terminal.

These days computers are a lot more powerful, and 'the terminal' is just an app. Technically we call it a terminal emulator.

There are other terminal apps #

Apple's Terminal is like a Ford Escort. It's pretty basic, it doesn't have many extras, but it comes with the job and doesn't cost you anything to drive.

If you want more features -- a better stereo, nicer wheels -- you can go shopping and get yourself a nicer model. There's iTerm 2, Warp, and a bunch of others.

You can even get them for your iPad.

But when you're just learning, stick with the simple car. I still use Terminal; it does everything that I need.

Launching Terminal #

Let's get your seat and mirrors adjusted. Launch Terminal, which is in your Mac's
/Applications/Utilities folder.

By the way, that notation with the slashes -- it means something very specific, which you'll soon understand. :-)

You'll be greeted by a fairly austere window.

I like to feel more like an old-school nerd when I'm at the CLI, so I set my default terminal to have green text on a black background. You can do that in Terminal's Settings: on the Profiles tab, select Homebrew,^[1] and click Default at the bottom of the list.

I also bump up my font size, which you can do on the right under Font.

Now hit Command-N to get a new window.

😎

Tip: duplicate the default profiles #

You can modify these profiles to your heart's content. If you select one of the defaults and click the three-dots-in-a-circle icon at the bottom of the list, you can Duplicate Profile. Now if you mess it up you can just delete it and start again.

We haven't started the car yet #

It's important to note that what you're messing about with here is the Terminal application's settings. There's no harm you can do here, other than making it look ugly.

We haven't put the key in the ignition yet. Let's do that and make sure it starts.

Start the engine #

It can help to see some text in the otherwise-empty window. So let's type your first command, which I'm not going to explain. It's just a command that will fill up your window with text.

Crucially, it's totally harmless.

Type printenv and hit return.

Shut it down #

To close this window, you have a few options.

Type logout.
Type exit.
Press Control-D.
Close the window using the red button at the top right.

They all do the same thing. I prefer logout because it feels more nerdy. Control-D is also very old-school.

Closing the window feels like the least correct thing to do.

Homework #

1: Have the window close automatically #

When you use one of the first three methods, the window won't actually close. Instead you'll be left looking at this text:

Saving session...completed.

[Process completed]

Figure out how to make it so that when you type logout, the window closes. Have a look around Settings, but use the internet if you're not sure.

2: Why don't I like using the red button? #

I said that closing the window using the red button felt like the 'least correct' thing to do.

Why?

Unrelated to the CLI tool that we'll learn about later. ↩︎

Computers are like cars

2024-05-29T13:55:00Z

Thanks, Johnny, this is outrageously exciting to my aspiring-geeky heart!

So I've done my assignment re- layers of abstraction. Makes perfect sense.

Just like my car's ignition button, I'm aware there's an organised, predictable series of events that take place once the button is pushed. Each event relies on those that came before it (pistons, oil, petrol, etc), but I don't have to think of any of that when I'm buckling up.

Computers be no different!

What is the command line?

2024-05-28T02:00:00Z

Your computer has many 'languages', or ways of 'thinking', internally.

The phrase '(it's all just) ones and zeroes' represents the fact that, at its very lowest level, your computer is literally just passing around information that looks like 1010111110101000100111010010110010.

(It's made of transistors, and they can only be on 1 or off 0.)

That's not very friendly for us humans, so over the years we've abstracted away from 1010111... by creating higher-level languages. The next-least-complicated language is called assembly.^[1]

LDA #$01
STA $0200
LDA #$05
STA $0201
LDA #$08
STA $0202

Okay, still not what you'd call friendly. Let's try some JavaScript: a higher-level language than assembly.

const firstname = "Johnny";
const nickname = "Decimal";
const surname = "Noble";

console.log(`Hi, ${firstname} ‘${nickname}’ ${surname}.`);

Better! You don't have to know JavaScript to at least guess what that's going to do.

If we keep going, we can abstract away this idea of languages entirely, and end up with the graphical user interface, or GUI.

So why would you bother learning a language when you can just go around clicking buttons?

Control #

You can click a button because some designer in Seattle designed the program to have a button.

But what if you want more granular control? What if there isn't a button for the thing you want to do?

Then you crack open the command line.

Because at the end of the day, that button passed a command to a high-level language which translated it and passed it down to a lower-level language which translated it to assembly which your computer translated to ones and zeros which is all it can understand.

So if you can insert yourself in that chain, if you can start talking some of these higher-level languages, you can get more control. You can do whatever you want.

The command line is how you talk to your computer in a high-level language.

Next, I'll explain how you do that.

Homework #

Do a bit of reading on abstraction layers. But you don't need to go deep on theory here: as long as you've got the idea, we'll move on.

This is not a scientifically complete list of computer languages. ↩︎

Introduction & goals

2024-05-28T01:00:00Z

On Mastodon, Ellane mentioned that she'd like to 'learn the command line'. What she told Johnny was that she wants to:

understand what the command line IS

learn how not to stuff up your machine

learn what language it speaks

understand what commands DO, where things go

know what Homebrew is, why people use it, what it does, and how it does it.

Also she has a 'burning ambition to learn plain text accounting (hledger, specifically)'. So that's where we're headed.

And so that's what we're going to do here. From zero to hero: I'm going to teach Ellane the command line.

Ellane learns the command line

Install some (Homebrew) packages

hledger #

Homework #

Homebrew

Package managers #

Other hledger options #

Install Homebrew #

🚨 🛑 ‼️ 🚨 🛑 ‼️ #

The installation command #

/bin/bash -c #

"$( ... )" #

curl 🟢 #

Caution to the wind #

A rapid advance

Ellane responds... #

Later that day... #

Johnny... #

Ellane... #

Johnny... #

Lots of feedback

Bookmarks? Shortcuts? #

Using the home-row keys #

Wrap at word breaks? #

Capitalisation of things #

Touch typing #

Searching and navigating #

man man #

Less is more

Do you have a plain text file handy? #

Let's view a file #

less 🟢 #

It'll show the file #

^ means the control key #

Search is interesting #

Homework: read all of the less help #

man pages #

Convention: indicating flags and arguments #

Keep reading #

man is less #

BUILTIN(1) #

Now you can view anything #

drwxr-xr-x

Flags and options

Behaviour modifiers #

Combining flags #

You can still specify an argument(s) #

Conventions #

Flags-as-words #

...and this is now an option #

All together now #

Everything is just a variety of this #

Homework #

Case-sensitivity, ttys, and the prompt

Case-sensitivity #

ttys #

The prompt #

A question of case

this\that #

Is case important? #

What's a tty? #

Escape arguments, completely

How to 'escape' this problem #

Not just spaces #

Remember, any character #

Tab completion saves the day #

Multiple results #

What's this got to do with spaces? #

Homework #

1. "A folder in quotes" #

2. this\that #

3. Too much escaping #

It does not like spaces

File paths

cd'ing to a nested folder #

The / forward slash #

Specify 'my home folder' #

. and .. also have special meaning #

This works everywhere #

You can combine all of this #

`hledger` #

Other `hledger` options #

`/bin/bash -c` #

`"$( ... )"` #

`curl` 🟢 #

`man man` #

`less` 🟢 #

`^` means the `control` key #

Homework: read all of the `less` help #

`man` pages #

`man` is `less` #

`BUILTIN(1)` #

`ttys` #

`this\that` #

1. `"A folder in quotes"` #

2. `this\that` #

`cd`'ing to a nested folder #

The `/` forward slash #

`.` and `..` also have special meaning #

`/Users/ellane/Desktop` #

The `shared` user #

New command: `cd` 🟢 #

New command: `ls` 🟢 #

New command: `pwd` 🟢 #