Install Gritpack

The installer for Mac, Windows and Linux, the one-line installs, PATH, upgrades

Chapter 2 of 34Current for Gritpack 1.2.63Source: docs/guide/02-install.md

You want the gritpack command on your computer, kept up to date, without learning anything about Gritpack first. There is one installer for each platform. You download it, open it and confirm, and it sets up the newest Gritpack for your user. Gritpack then keeps itself up to date the same way it keeps any other application up to date.

What you will be able to do

  • install Gritpack on a Mac, on Windows or on Linux;
  • install it from a terminal with one line, including on servers;
  • find where it lives and make sure your shell finds it;
  • check which version you have, upgrade it and remove it.

The short way

Open gritpack.org/install in a browser. The page offers a download for your platform. Each download is the same small installer program, named for what it installs:

PlatformDownloadWhat to open
Mac with Apple silicongritpack.org/download/macgritpack.installer, from the downloaded zip
Windows on x86-64gritpack.org/download/windowsgritpack.installer.exe
Linux on x86-64gritpack.org/download/linuxgritpack.installer, run from a terminal

The installer shows what it is about to install (the package, its version and its description, and the hub it comes from) and asks you to confirm. Then it downloads Gritpack, checks the download against the digest the hub recorded, installs it for your user, and offers to put Gritpack's command folder on your PATH.

Nothing is installed for other users of the computer, and nothing needs administrator rights.

The first time on a Mac

The installer is not yet signed with an Apple Developer ID, so the first time you open it macOS says it cannot check it. Open System Settings, Privacy & Security, choose Open Anyway, then open the installer again.

The first time on Windows

The installer is not yet signed, so Windows may say it protected your PC. Choose More info, then Run anyway. With Smart App Control turned on, Windows refuses unsigned programs altogether until the installer is signed; use the PowerShell line below instead, or install on a machine without it.

When you double-click the Windows installer, a console window shows for a moment before the installer's own window opens. That is expected: the same program also works in a terminal.

From a terminal

On Linux, and in a Mac terminal, one line does the same thing:

curl -fsSL https://get.gritpack.org/install/gritpack | sh

The script downloads the installer for your platform, checks it against a SHA-256 digest the hub writes into the script, and runs it. If the digest does not match, it stops before installing anything. The installer then asks you to confirm, on your terminal, even though the script itself came through a pipe.

Here is a real run, on Linux:

$ curl -fsSL https://get.gritpack.org/install/gritpack | sh
Install gritpack 1.2.63 from get.gritpack.org?
  Universal package, module-graph, and software distribution client
Downloading gritpack 1.2.63 … verified
Installing gritpack … ok
...
gritpack is ready: run `gritpack`

On Windows, in PowerShell:

irm https://get.gritpack.org/install.ps1/gritpack | iex

That script does the same for Windows: it downloads the installer, checks its digest and runs it.

Careful. Piping a script from the internet into a shell runs it. Read it first if you like: curl -fsSL https://get.gritpack.org/install/gritpack prints it. It is about forty lines, and it only downloads, checks and runs the installer.

Without questions

On a server, in a container or in a script there is nobody to answer the question. Pass --yes to the installer. With sh, arguments go after sh -s --:

curl -fsSL https://get.gritpack.org/install/gritpack | sh -s -- --yes

Two more installer options are useful there:

  • --no-modify-path leaves your shell's start-up files alone. The installer then tells you which folder to add to PATH yourself.
  • --home <dir>, or the GRITPACK_HOME environment variable, installs into another folder instead of ~/.frogfish/gritpack.

In PowerShell, irm ... | iex cannot pass arguments. This form can:

& ([scriptblock]::Create((irm https://get.gritpack.org/install.ps1/gritpack))) --yes

Without a terminal and without --yes, the installer stops rather than guess.

Where Gritpack lives

Everything Gritpack keeps for your user lives in one folder, its home:

PlatformGritpack home
macOS and Linux~/.frogfish/gritpack
WindowsC:\Users\<you>\.frogfish\gritpack

Inside it, the folders you may meet are:

FolderWhat it holds
bin/The commands of installed applications, gritpack among them
store/The installed applications' files, one folder per exact version
cache/Downloaded package files, shared by every project
credentials/Your hub logins, when they are kept as files
config.tomlYour login profiles

bin/ is the folder that must be on your PATH. The installer offers to add it to your shell's login profile (~/.zprofile, ~/.bash_profile or ~/.profile), once. On Windows it adds it to your user Path. Open a new terminal afterwards so the change is picked up.

If you said no, or used --no-modify-path, add it yourself, for example in ~/.zprofile:

export PATH="$HOME/.frogfish/gritpack/bin:$PATH"

GRITPACK_HOME moves the whole home somewhere else. Chapter 29 lists the other environment variables.

Check what you have

$ gritpack version
gritpack 1.2.63+build-1325
platform:   linux-x86_64
executable: /home/ada/.frogfish/gritpack/store/sha256/1250a1fb.../bin/gritpack
license:    Frogfish Binary License 1.0 (run `gritpack --license` to read it)
upgrade:    gritpack app upgrade gritpack

gritpack --version prints only the first line. The executable line shows that the command in bin/ points into the store, at one exact installed version. The upgrade line tells you how to move to a newer one.

gritpack help lists every command in groups. You will meet most of them in this guide. gritpack <command> --help explains one command.

Keep it up to date

Gritpack installed itself as an ordinary application, so it upgrades like one:

$ gritpack app upgrade --check
gritpack 1.2.63 current
$ gritpack app upgrade gritpack

--check only reports. Without it, Gritpack downloads the newest version for your platform, checks it, unpacks it next to the old one, and then switches the gritpack command over. A version that is already running keeps working until it exits. Chapter 14 explains applications in full.

Remove it

To remove the gritpack command and its installed files:

$ gritpack uninstall gritpack
uninstalled gritpack 1.2.63 commands=gritpack

That leaves your logins, your other applications and the download cache in ~/.frogfish/gritpack. To remove everything:

  1. Log out of each hub first, so your credentials are revoked rather than just forgotten: gritpack auth logout --profile <name> for each name gritpack auth list shows (chapter 21).
  2. Uninstall your other applications, or not, as you like.
  3. Delete the folder ~/.frogfish/gritpack (on Windows, C:\Users\<you>\.frogfish\gritpack).
  4. Remove the PATH line the installer added to your shell's login profile, or the entry in your Windows user Path.

Careful. Deleting the folder deletes your login credentials kept as files. Without step 1 the hub still counts them as valid until they expire.

What just happened

You installed Gritpack the way you will later install applications with it: a download checked against a digest, unpacked into a per-user store, and a command placed in ~/.frogfish/gritpack/bin. Gritpack is now one of its own applications, so gritpack app upgrade keeps it current.

You can stop here

If you only needed the gritpack command, you have it.

Next