Shell comforts

Aliases, completion, the pager, help topics and environment variables

Chapter 29 of 34Current for Gritpack 1.2.63Source: docs/guide/29-shell-comforts.md

Once you use Gritpack every day, small things start to matter: typing the same long command, remembering a flag's spelling, a long info scrolling past the top of the window. This chapter collects the features that make the shell pleasant: your own short names for commands, tab completion, the pager, the built-in help topics and the environment variables that set defaults. None of them changes what a command does.

What you will be able to do

  • Give a long command a short name of your own, with arguments.
  • Turn on tab completion in bash, zsh, fish or PowerShell.
  • Choose, or turn off, the pager for long output.
  • Find help without leaving the terminal.
  • Set defaults with environment variables instead of repeating flags.

Your own short names: aliases

gritpack alias set gives a command a short name. The expansion is written without gritpack and quoted as one argument:

$ gritpack alias set yk 'package yank'
yk runs `gritpack package yank`
$ gritpack alias set s 'search --limit 5'
s runs `gritpack search --limit 5`

Now gritpack s text runs gritpack search --limit 5 text. Anything you type after an alias is added at the end.

When the extra arguments belong in the middle, use $1, $2 and so on. Each takes the argument in that position; any arguments left over are added at the end as before:

$ gritpack alias set ver 'info $1 --jq .families[0].family.publications[].version'
ver runs `gritpack info $1 --jq .families[0].family.publications[].version`
$ gritpack ver @ada/textkit
1.0.1

Keep the single quotes when you set an alias that contains $1. In double quotes your shell would replace $1 before Gritpack ever saw it.

List and remove aliases:

$ gritpack alias list
s    gritpack search --limit 5
ver  gritpack info $1 --jq .families[0].family.publications[].version
yk   gritpack package yank
$ gritpack alias delete s
removed the alias s

gritpack alias list --json prints them as one JSON object, name to expansion. They are stored in ~/.frogfish/gritpack/aliases.toml, a small file you can copy to another machine:

[aliases]
ver = "info $1 --jq .families[0].family.publications[].version"
yk = "package yank"

A Gritpack command always wins. You cannot make an alias with the name of a command, or of an old command name that still works:

$ gritpack alias set search 'info'
search is a gritpack command already; an alias cannot replace it
$ gritpack alias set whoami 'auth status'
whoami is a gritpack command already; an alias cannot replace it

That rule means a new Gritpack release can never be shadowed by an alias you made last year, and a script that calls gritpack search always gets search.

Careful. gritpack help alias set shows the example info $1 --jq .families[0].versions. In 1.2.63 that path prints null, because the versions sit one level deeper. Use .families[0].family.publications[].version, as above.

Tab completion

gritpack completion <shell> prints a completion script for bash, zsh, fish, PowerShell or elvish. It completes commands, subcommands, flags and the values of flags that have a fixed list, such as --format. Save it where your shell looks for completions, then start a new shell:

# bash
gritpack completion bash > ~/.local/share/bash-completion/completions/gritpack

# zsh (a directory in $fpath; run `echo $fpath` to see them)
gritpack completion zsh > "${fpath[1]}/_gritpack"

# fish
gritpack completion fish > ~/.config/fish/completions/gritpack.fish

In PowerShell, load it into the current session, and add the same line to $PROFILE to keep it:

gritpack completion powershell | Out-String | Invoke-Expression

gritpack completion --help shows the same instructions. Regenerate the script after upgrading Gritpack, so new commands complete too.

From Cargo. This is the same idea as rustup completions, and the scripts come from the same library that most Rust command-line tools use.

The pager

Three commands can print a lot: info, search and admin audit-log. On a terminal, their human output goes through a pager so you can scroll it. Gritpack chooses the pager in this order:

  1. GRITPACK_PAGER, if it is set;
  2. PAGER, if it is set;
  3. less.

When it runs less and LESS is not set, it sets LESS=FRX: quit at once if the output fits on one screen, keep colours, and do not clear the screen when you leave. To turn the pager off, set GRITPACK_PAGER to an empty value or to cat:

export GRITPACK_PAGER=cat

JSON output and output sent into a pipe are never paged, so scripts are not affected. Windows does not page.

Help without leaving the terminal

Every command and group has --help. -h gives the short form, with one line per flag; --help gives every flag with its full description, its default and the environment variable that sets it. The everyday commands end their help with examples.

gritpack help with no argument shows the commands in groups, then the help topics. A topic is a short page about something that is not one command:

TopicWhat it covers
gritpack help environmentEvery environment variable Gritpack reads, and the flag each one sets
gritpack help exit-codesWhat each exit code means, and JSON errors
gritpack help formattingJSON output, --json=fields, --jq, NDJSON and scripting
gritpack help profilesWhere logins, administrator profiles and aliases are kept

gritpack help <command> works too, and is the same as gritpack <command> --help.

When you mistype a command, Gritpack suggests the nearest ones:

$ gritpack serch x
error: unrecognized subcommand 'serch'

  tip: some similar subcommands exist: 'serve', 'search'

(serve is an old name that is no longer listed and does no work in the client. You wanted search.)

Old command names

The command line was regrouped in 1.2.61. The old names still work, and print a one-line note on standard error naming the new one:

$ gritpack whoami
note: `gritpack whoami` is now `gritpack auth status`; the old name stops working in 1.4.0.
account=01a1e865-dd2b-7f10-9340-1658dbafa174 email=ada@example.com status=Active
...

The note is silent when you asked for JSON errors, so scripts keep working while you update them. This guide uses only the new names.

Version and where Gritpack is

gritpack version shows the version, the platform, where the running executable is, and how to upgrade it:

$ gritpack version
gritpack 1.2.63+build-1325
platform:   linux-x86_64
executable: .../gritpack
license:    Frogfish Binary License 1.0 (run `gritpack --license` to read it)
upgrade:    gritpack app upgrade gritpack

The executable line is the full path of the program that ran. For a copy the installer set up, the gritpack command in ~/.frogfish/gritpack/bin is a link into ~/.frogfish/gritpack/store/, so the line may name a folder there. When two copies of Gritpack are installed, it tells you which one your shell found. gritpack --version prints only the first line.

Defaults from environment variables

Every flag that connects to a hub or chooses a place on disk has an environment variable, shown in each command's --help as [env: ...]. A flag on the command line always wins over the variable. The ones people set most:

VariableDefault it sets
GRITPACK_PROFILEThe login profile to use (--profile)
GRITPACK_HOMEGritpack's own directory, normally ~/.frogfish/gritpack
GRITPACK_CACHE_DIRThe download cache (--cache-dir)
GRITPACK_PACKAGES_DIRWhere a project's packages go (--packages-dir), normally packages
GRITPACK_JOBSDownloads at once, 1 to 64 (--jobs), normally 4
GRITPACK_ERROR_FORMAThuman or json errors (--error-format)
GRITPACK_PAGER, PAGERThe pager
GRITPACK_ADMIN_PROFILEThe administrator profile (admin --profile)
NO_COLORWhen set, help and errors have no colour
CIWhen set, Gritpack never prompts

gritpack help environment prints the full list. Two of them are worth a word:

  • GRITPACK_HOME moves everything at once: logins, credentials, cache, installed applications, aliases. Point it at an empty directory to try something without touching your real setup. FROGFISH_HOME moves the parent directory instead, and Gritpack uses its gritpack folder.
  • GRITPACK_PROFILE is handy in a shell where you work on one hub all day: export GRITPACK_PROFILE=work and every command uses that login.

What just happened

You made your own short commands with aliases, turned on completion, chose how long output is paged, found the help topics, and moved defaults into environment variables. None of it changed what any command does, and none of it affects scripts that ask for JSON.

You can stop here

If you just wanted the command line to be more comfortable, you are done.

Next

If you build tools on top of Gritpack, read Tools and agents. If you look after a hub, go on to Administering a hub.