Installing applications
gritpack install, app list, app upgrade, app which, uninstall
Some packages are not libraries you build against but programs you run: a
code generator, a formatter, a deployment tool, Gritpack itself. You want to
type one command, get the program on your PATH, and later move it to a new
version without thinking about where its files live. That is what
gritpack install and the gritpack app commands are for. They install for
your user only, never ask for an administrator password, and never touch
/usr, Homebrew or the system package manager.
What you will be able to do
- install a command-line application from the public hub or your private hub;
- see what you have installed, and which application owns a command;
- check for newer versions and upgrade, one application or all of them;
- remove an application cleanly;
- understand which hub an application comes from, and why that choice is safe.
Install one application
The public hub, get.gritpack.org, serves applications to anyone, without an
account. Installing one is a single command:
$ gritpack install @frogfish/scroll-throttle
resolving @frogfish/scroll-throttle latest for x86_64-unknown-linux-gnu from the configured registry chain…
downloading and verifying 1 package…
installing and activating commands…
installed @frogfish/scroll-throttle 1.0.0 from https://get.gritpack.org:443 into ~/.frogfish/gritpack commands=scroll-throttle integrity=verified provenance=registry-recorded
Read the last line from left to right. Gritpack installed version 1.0.0, it
says which hub the package came from, the files went into your Gritpack home,
and the package provides one command, scroll-throttle. integrity=verified
means every byte matched the digest the hub recorded when the version was
published. provenance=registry-recorded means the hub vouched for who
published it and under which name. Neither is a claim that the program is safe
to run: Gritpack checks that you got exactly what the publisher published, not
what the program does.
The first line names the platform Gritpack looked for,
x86_64-unknown-linux-gnu here. An application is published once per
platform, and Gritpack picks the one for your machine. If there is none, it
says it cannot resolve the package rather than install something that will not
run.
To ask for a particular version, add it after the name. A plain version is taken as a requirement, as everywhere in Gritpack:
gritpack install @ada/hello-tool 1.0.0
gritpack install @ada/hello-tool '^1'
Careful. In zsh, a word that starts with
=is expanded by the shell. Quote an exact pin:gritpack install @ada/hello-tool '=1.0.0'.
gritpack app install is the same command under the app group. Use
whichever you like; this guide uses the shorter gritpack install.
Where the files go, and PATH
Everything lives in your Gritpack home, ~/.frogfish/gritpack unless you
moved it with GRITPACK_HOME:
~/.frogfish/gritpack/
bin/ one entry per command, the only directory you put on PATH
store/sha256/ each installed version, unpacked into a folder named by its digest
receipts/ one record per installation: what, which version, from where
cache/ downloaded package files, shared with projects
On Linux and macOS each command in bin/ is a symbolic link into the store.
On Windows it is a small launcher, bin\<command>.exe, beside a one-line
bin\<command>.target file naming the program it runs.
The installer described in Installers and download links
offers to add ~/.frogfish/gritpack/bin to your PATH. If you installed
Gritpack another way, add it yourself once, for example in ~/.zprofile or
~/.bashrc:
export PATH="$HOME/.frogfish/gritpack/bin:$PATH"
Open a new terminal and the commands work by name:
$ hello
hello from hello-tool 1.0.0
Under the hood. A version's folder in
store/is written once and never changed. An upgrade unpacks the new version into a new folder and then switches the commands to it, so a program that is already running keeps its files. Gritpack never runs code from a package while installing it: there are no install scripts.
See what you have
gritpack app list shows every application installed for your user:
$ gritpack app list
@ada/hello-tool 1.0.0 provenance=registry-recorded origin=https://packages.example.com:443 commands=hello
@frogfish/scroll-throttle 1.0.0 provenance=registry-recorded origin=https://get.gritpack.org:443 commands=scroll-throttle
When a command on your PATH surprises you, ask which application owns it:
$ gritpack app which hello
hello -> @ada/hello-tool 1.0.0 (https://packages.example.com:443)
Both commands take --json. app list --json adds the exact digest, the
platform, the installation's ID, when it was installed, and store_path, the
folder holding that version's files:
$ gritpack app list --json
[
{
...
"dialect": "application/cli",
"entrypoints": {
"hello": "bin/hello"
},
"origin": "https://packages.example.com:443",
"package": "@ada/hello-tool",
"provenance": "registry_recorded",
"store_path": "~/.frogfish/gritpack/store/sha256/046afd42631eca55899b9e88d2205d520bb2135c13b5fcb1132f8b8f69d65df7",
"target": "x86_64-unknown-linux-gnu",
"version": "1.0.0"
}
]
A program that wants to find the files of another installed application, such as a launcher looking for a bundle of resources, should read this list instead of searching folders on disk.
Upgrade
When a publisher releases a new version, check first, then upgrade:
$ gritpack app upgrade --check
@ada/hello-tool 1.0.0 -> 1.1.0 available
$ gritpack app upgrade
downloading and verifying 1 package…
installing and activating commands…
@ada/hello-tool 1.0.0 -> 1.1.0 upgraded
$ hello
hello from hello-tool 1.1.0
With no names, app upgrade looks at every installed application. Name one or
more to upgrade only those:
gritpack app upgrade @ada/hello-tool
Each application is upgraded on its own. If one fails, the others still
upgrade, the report says failed for the one that did not, and the command
exits with an error so a script notices. An application that is already at its
newest version reports current:
$ gritpack app upgrade
@ada/hello-tool 1.1.0 current
@frogfish/scroll-throttle 1.0.0 current
Gritpack is an application too. If you installed it with the installer, it upgrades itself the same way:
gritpack app upgrade gritpack
gritpack version prints this line under upgrade: as a reminder.
From npm.
gritpack app upgradeis the counterpart ofnpm update -g, andgritpack installofnpm install -g. Project dependencies are a different thing in Gritpack:gritpack updateandgritpack upgradeact on a project'sgritpack.toml, never on installed applications. See Keeping up to date.
Running gritpack install again for an installed application also moves it to
the newest version, or to the version you name. That is how you go back to an
older version:
$ gritpack install @ada/hello-tool 1.0.0
resolving @ada/hello-tool 1.0.0 for x86_64-unknown-linux-gnu from https://packages.example.com:443 (recorded by the existing installation)…
downloading and verifying 1 package…
installing and activating commands…
installed @ada/hello-tool 1.0.0 from https://packages.example.com:443 into ~/.frogfish/gritpack commands=hello integrity=verified provenance=registry-recorded
Note the words "recorded by the existing installation". The next section is about why that matters.
Which hub an application comes from
With no login, Gritpack knows only the public hub, and every install comes
from get.gritpack.org.
Once you log in to a private hub (Logging in), Gritpack asks your hub first and the public hub second. It moves on to the public hub only when your hub answers, with your login, that it has no package of that name at all. So with a private login active, this still installs from the public hub:
$ gritpack install @frogfish/scroll-throttle
resolving @frogfish/scroll-throttle latest for x86_64-unknown-linux-gnu from the configured registry chain…
...
installed @frogfish/scroll-throttle 1.0.0 from https://get.gritpack.org:443 into ~/.frogfish/gritpack commands=scroll-throttle integrity=verified provenance=registry-recorded
and this installs from your hub:
$ gritpack install @ada/hello-tool
resolving @ada/hello-tool latest for x86_64-unknown-linux-gnu from the configured registry chain…
...
installed @ada/hello-tool 1.0.0 from https://packages.example.com:443 into ~/.frogfish/gritpack commands=hello integrity=verified provenance=registry-recorded
Three rules keep this safe:
-
Only a clear "no such name" falls through. If your hub cannot be reached, rejects your login, or has the name but cannot offer it right now (for example because an administrator quarantined it), the install stops with an error. It never quietly fetches a public package of the same name instead. That is what protects you from someone publishing a look-alike name on the public hub.
-
Once installed, an application stays with its hub. The receipt records where it came from, and every later install, reinstall and upgrade of it asks only that hub.
-
--frommeans exactly one hub. To use one hub and no other for this command, name it:gritpack install @frogfish/scroll-throttle --from get.gritpack.org--fromnever falls back. If the package is not on that hub, the command fails:$ gritpack install @ada/hello-tool --from get.gritpack.org
resolving @ada/hello-tool latest for x86_64-unknown-linux-gnu from get.gritpack.org… cannot resolve @ada/hello-tool: root requires @ada/hello-tool *
For a private hub, --from takes the hub's address, and --from-cert,
--from-key and --from-ca take a certificate if no login profile covers
it.
If you have logins to several private hubs, app upgrade uses, for each
application, the login that serves the hub it came from, so applications from
different hubs upgrade in one run. Hubs and sources
explains the same rules for project dependencies.
Two applications, one command name
Two applications may not both own the same command. Gritpack refuses before it changes anything:
$ gritpack install @ada/hello-two
resolving @ada/hello-two latest for x86_64-unknown-linux-gnu from the configured registry chain…
downloading and verifying 1 package…
installing and activating commands…
global command "hello" is already owned by @ada/hello-tool
The command exits with code 6, a conflict. Uninstall the other application
first if you want to switch. Gritpack also refuses to replace a file in bin/
that it did not put there, so a program you copied in by hand is never
overwritten.
Remove an application
$ gritpack uninstall @ada/hello-tool
uninstalled @ada/hello-tool 1.1.0 commands=hello
gritpack app uninstall is the same command. It removes the application's
commands from bin/ and its receipt. The version's folder in store/ is left
in place, so a copy of the program that is still running keeps working. In
1.2.63 Gritpack does not yet remove unused store folders by itself; they are
safe to leave.
For automation
For automation.
install,uninstall,app list,app whichandapp upgradetake--jsonand--error-format json. Every one of them takes--home <dir>to work on a Gritpack home other than yours, which is handy in tests.app upgrade --check --jsontells a script what is out of date without changing anything. See Scripting with JSON.
Making your own application installable
Any package becomes an installable application when its gritpack.toml maps
command names to executable files with an [entrypoints] table:
[package]
name = "@ada/hello-tool"
version = "1.0.0"
dialect = "application/cli"
encoding = "executable/native"
target = "x86_64-unknown-linux-gnu"
description = "Prints a friendly greeting"
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
files = ["bin/hello", "README.md", "LICENSE"]
[entrypoints]
hello = "bin/hello"
The rules:
-
Each key is a command name: letters, digits,
.,_and-, starting with a letter or digit, at most 64 characters. Names are compared without regard to case. -
Each value is a path inside the package to a regular file that is marked executable. Gritpack checks this when you pack:
$ gritpack pack --output ../hello-tool-1.0.0.gpk
invalid manifest: entrypoint "hello" target "bin/hello" must be a regular executable package file $ chmod +x bin/hello $ gritpack pack --output ../hello-tool-1.0.0.gpk packed @ada/hello-tool 1.0.0 dialect=application/cli encoding=executable/native target=x86_64-unknown-linux-gnu files=4 entrypoints=hello payload_sha256=9b63f1b1... -> ../hello-tool-1.0.0.gpk
- Set
targetto the platform the program runs on, using the names Gritpack reports, such asx86_64-unknown-linux-gnu,aarch64-apple-darwinorx86_64-pc-windows-msvc. Publish one package per platform, all with the same name and version;gritpack installpicks the one that matches the machine. A package with notargetis not offered bygritpack install. dialect = "application/cli"is a label for people and tools that filter search results. Gritpack attaches no rules to it, and you may use another label that suits your application.- Gritpack carries regular files, with or without the executable bit, and symbolic links that stay inside the package. It does not carry file owners, other permission bits, or empty directories.
- An application may be laid out however it likes, for example a folder with a binary, icons and data files. Gritpack does not look inside; it only activates the commands you list.
Publishing it is the same as publishing any package, and is the subject of Publish your first package.
What just happened
gritpack installresolved an application for your platform, checked every byte against the hub's record, unpacked it into a folder that never changes, and linked its commands into~/.frogfish/gritpack/bin.app listandapp whichshow what is installed and where it came from.app upgrademoves applications forward, each from the hub it came from;installwith a version moves one to exactly that version.- With a private login, your hub is asked first, and the public hub only when
your hub has no such name.
--frompicks exactly one hub. uninstallremoves the commands and the record.
You can stop here
If you only want to install and update command-line tools, you are done.
Next
- Installers and download links covers the one-click installer that sets up Gritpack and an application for people who have never heard of Gritpack.
- Optional: Publish your first package to put your own application on a hub.