Command line interface: A beginner's guide to what it is and how it works

Have you asked yourself, “What is a command line interface?”

Perhaps you’re well aware of a particular command line interface (CLI) in your life, maybe you’ve even used one regularly, but are you aware of their true power? Did you know that they are often lurking under the covers of your favorite applications and services, just waiting to be discovered and leveraged?

Here, we will reveal what these CLIs really are, how they work, and how to use them to save development time with Contentful.

What is a command line interface?

A command line interface is a text-based way of communicating with your computer's applications by typing commands. The first CLI was created by Steve Bourne in the 60's for the early Unix systems, before the advent of graphical user interfaces (GUIs).

GUIs, with their visual elements (like windows, icons, and menus), were built on top of the operating system's CLIs, acting as a more accessible interface, gloss, or even abstraction, over the functions provided by the CLI. Today, many applications are typically built directly from the functionality of their underlying CLI.

One popular application built directly on top of its lesser-known CLI is WinRAR. For developers, there are many GUI tools available that sit directly on top of the Git command line utility.

You can find that the CLI underneath the application is like the Swiss Army knife to your system that you were always looking for. CLIs often bring deeper functionality, better access, and more customizable features than the visible user interface does, but with great power comes great responsibility: Command line instructions often — but not always — have the ability to execute without asking “Are you sure?” before doing something destructive and irreversible.

Generally, non-technical users stick to using GUIs and we, as developers, can choose to use a CLI if we need to automate repetitive or bulk tasks, work more efficiently, or integrate with other software. For example, most users will use the file browser to delete files, whereas developers will often use the command line to delete files because it avoids leaving the keyboard.

Basic CLI commands

As some commands don’t require programming, systems, or other technical knowledge to be useful for everyone, some system-agnostic CLI commands that you might already have used include:

• dir or ls – Both of these simply list out the contents of the current directory. The first is typical of DOS (one of the earliest well-known CLIs) while the second is now more common (even on Windows).

• ping – This is a networking command that tests the connection between your computer and another device, website, or IP address. This is the CLI equivalent of a sonar ping, letting you know if the device is available or not and showing how long it took to respond.

Let's take a look at how to access your operating system's CLI, find out what it can do, and point out some good and bad things to watch out for.

Accessing your CLI

To use your CLI, you need to find and open it. Here’s a quick summary of how to do this on the three major platforms:

Windows Command Prompt and PowerShell

In years past, Windows had only the DOS prompt (now Command Prompt).

These days it is more common to use PowerShell, a more flexible and Unix-styled CLI that comes bundled with a huge number of built-in commands, though Command Prompt still exists.

You can access both Command Prompt and PowerShell from the Start menu, but a faster way is to press the Windows key, type either “cmd” (for Command Prompt) or ”powershell” (for PowerShell) and press Enter.

Mac and Linux distributions

Apple Mac and Linux users have Terminal. This can be launched from the Applications directory, Launchpad, or the system search.

How does a CLI work?

The CLI is a text-based input that takes your command instruction, executes it, and displays the response as text output. These commands may or may not produce text output in the terminal window, but will be doing something in memory, on the filesystem, or on the network. If a command takes some time, you may have to wait for its output before you can enter more instructions.

Navigation

Moving between directories (also known as folders) is quite straightforward. In the terminal, you can see what directory you're in by entering pwd (be sure to press Return (Mac) or Enter (Windows) after typing pwd). The CLI will print out the full path of the current “working directory” — the directory you are currently in, along with the path to it from the root of the filesystem.

The path is the location of the file or directory, even your current directory, that you want to refer to, for example, /Users/Jeff or C:\MyFile.txt. On Mac (and other Linux-based operating systems), paths start with and are delimited by a forward slash. On Windows, full paths start with a letter and use backslashes, like C:\Users\Jeff.

To see the contents of the directory, enter ls and you’ll see the names of the files and directories in the current directory. You can confirm this by opening the directory explorer and navigating to the same directory.

To move into one of those directories in the CLI, enter cd <name of the directory>. After pressing Return or Enter, you may only see the prompt, but if you enter ls again you’ll see the contents of the newly current directory.

If you want to move back up to the parent directory — or up to the parent directory at any time — enter cd ... You can also enter cd <full path of desired directory> and (assuming you get the path correct) you will jump to that directory.

One trick is that, if the name of the destination directory (or file) is in the current directory, you can type the first few letters of its name, then hit Tab and the CLI will usually auto-complete the directory (or filename) for you (or as much as it can).

Another is using the up and down arrow keys to scroll through the history of your commands. This makes it easier to repeat previous commands and review what you’ve executed in the past — up to a surprisingly long time ago.

Parameters, arguments, and flags

Most, if not all, command line utilities (utility is another name for a command) can accept parameters. These generally take one of two forms: either a value (an argument) or a flag (like a switch). Let’s take a look at how these are used:

Flags

Providing a flag is like calling the command with a ticked checkbox to switch an option on. It modifies the command’s behavior, but does not need a value to specify the behavior. An example of this is the -a flag, which tells the ls (Mac Terminal, Windows PowerShell) command to list all files, including hidden ones, along with the visible files.

Notice in the screenshot comparison above that the view on the right contains three extra items. These are hidden directories, which the command without the `-a` flag, on the left, does not display.

Named parameters

Often, commands accept named parameters, the benefit of which is that they can be provided in any order. They usually take the form of the parameter name being prefixed with either one or two hyphens (depending on platform), and then a value.

A PowerShell example of a command accepting a named parameter value is:

Copy-Item -Path source.txt -Destination destination.txt

Here, -Path and -Destination are the parameter names and the values immediately following them are their values (sometimes called arguments).

Unnamed parameters

Commands will often accept unnamed parameter values (also often called arguments), as well. These can be used along with named parameters but will usually appear after the named arguments in a specific order, for clarity.

An example of an unnamed parameter is the Mac Terminal equivalent of the above command:

cp source.txt destination.txt

Here, the copy command accepts the filenames in a specific order, rather than their parameter values being provided in any order.

Built-in documentation and help

The vast majority of CLI tools will provide you with documentation for how to use their commands. These typically explain the syntax needed to run a command and list the options available to you. They aim to make commands self-explanatory and do this with a command line flag.

--help, -help and -h

Most CLI commands will support the flag --help or variations - often -h (again, depending on platform). Provide this flag after the name of the command and it will (usually) provide information. For example, commands like man and touch provide help about the arguments they accept with the -help and -h  flags, respectively.

Note: Some commands will support other help flags, such as -h or -H (for example, this is common on the Mac).

The Contentful CLI will list the available command arguments for environment management when you ask:

contentful space environment --help

Playing with help flags is a very safe way to learn about the features of a command.

Get-Help

In PowerShell, help is provided with the specific command Get-Help. You give it the name of the command you’re interested in as an argument.

man

An alternative to --help, at least on Linux-based operating systems, like Mac, is to use man. This stands for “manual” and will show a more detailed documentation page for any command whose name you provide as an argument (for example, man cp will show the documentation for cp).

Press Space or Return to move to the next page in `man` pages, and `q` to exit.

Authenticating with CLI tools

Some CLI tools, such as those that perform operations for a cloud service, will require that you authenticate your local copy of their CLI tool to their online service before they will grant you access to its facilities. This usually involves acquiring an API key from the provider’s online service and providing it as an argument when you log in with their CLI tool.

For example, the Contentful CLI tool takes a management token as an argument, which can either be generated by the Contentful web app or by using the Contentful CLI command itself:

contentful login --management-token <management-token>

The Contentful CLI also lets you generate the management token without using the web app, which can be useful for automation, scripting, or CI/CD.

Good use cases for a CLI

No doubt you’ve been a GUI user for a long time, so you might be wondering when you should look to the CLI for doing tasks. Here are some good scenarios where you can try replacing your trusty point-and-click interface with a keyboard-based alternative:

• Replace slow, manual tasks: Perhaps you have a GUI tool that downloads some data every day. Can that be performed with a CLI command rather than a journey through the UI? Perhaps it can be run “unattended” with automation.

• Repeated tasks: Perhaps you do something every day with a bunch of files? How would you do that task on the command line? Then try writing a script for your chosen CLI environment and replace the routine. For example, Contentful users often use the Contentful CLI tool to automate a migration (a change to their content model) across multiple different environments at once to save time.

• System admin: Some system functions and advanced features, often in operating systems, require admin permissions and may only be performed on the command line.

• Cloud computing: If you need to perform some large task, a command that can perform that task without opening a web browser might be helpful. For example, you could try bulk updating or deleting content that has a particular tag, such as bulk updating all old blog posts so they become "unpublished."

• Remote access: Servers, in the cloud or not, typically offer remote access. Loading up a remote desktop can be slow and cumbersome, but getting in and out with the command line makes the process much more fluid and efficient.

• Workflow: Make using the CLI part of your daily routine to help figure out which parts of your typical workflows can be automated, enhanced, or even replaced with command line help. This can include building up script files to act as super-commands.

Best practices

We’ve already signposted some warnings, but here are some tips to always keep in mind whenever you consider that tap-tap instead of the click-click:

• Know where you are executing your commands. You might think you’re in your temp directory when you decide to delete all those unnecessary files, but are you sure? No one wants to tell their boss they irrevocably deleted the finance spreadsheets.

• Read up on the commands. This is easy. Just go RTM. Read up on the arguments and flags that a command supports to know what your options are. Many developers have waited hours for something that could have taken seconds because they didn't think to check if an option existed to narrow the scope.

• Know which command you are executing. Some commands are destructive! You don’t want to be deleting everything when you meant to be copying everything. Check the usage of the command you’re about to run with the --help (or -help) flag — especially if it's your first time with it.

• Double-check the arguments. Again, this is especially important if you are executing a destructive command, like a delete. Make sure the parameters you pass into the command are correct — don’t assume that relative paths point to a particular file or directory; check them.

• Use –dry-run where available. Some command line tools let you test out the command before actually executing it. This is called a dry run and will give you feedback on what is expected to happen before it happens. Usually the flag is simply `--dry-run`, but again, the naming is not guaranteed.

• Keep your keys safe. When using authentication keys or tokens, be sure to keep them safe. This might mean encrypting them when using command line utilities in a deployment pipeline or using limited scope tokens when a user is executing commands. This will help prevent sensitive access tokens falling into the wrong hands and reduce the possibility of something terrible happening when they are used on an open system, like a user’s laptop.

Upping your game

Deciding to step into the world of the command line interface may feel like a bold move, but remember there is a wealth of information and support out there on the internet for any tool you choose to learn.

Whether it's packages to improve your frontend development or content management with Contentful, we applaud this bold step into a powerful environment. If you're already a Contentful user you can get started with the Contentful CLI and begin managing your content with super powers. If not, then sign up with Contentful to discover the benefits of a suite of managed content tools.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.