Shell comforts
Aliases, completion, the pager, help topics and environment variables
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 setshows the exampleinfo $1 --jq .families[0].versions. In 1.2.63 that path printsnull, 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:
GRITPACK_PAGER, if it is set;PAGER, if it is set;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:
| Topic | What it covers |
|---|---|
gritpack help environment | Every environment variable Gritpack reads, and the flag each one sets |
gritpack help exit-codes | What each exit code means, and JSON errors |
gritpack help formatting | JSON output, --json=fields, --jq, NDJSON and scripting |
gritpack help profiles | Where 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:
| Variable | Default it sets |
|---|---|
GRITPACK_PROFILE | The login profile to use (--profile) |
GRITPACK_HOME | Gritpack's own directory, normally ~/.frogfish/gritpack |
GRITPACK_CACHE_DIR | The download cache (--cache-dir) |
GRITPACK_PACKAGES_DIR | Where a project's packages go (--packages-dir), normally packages |
GRITPACK_JOBS | Downloads at once, 1 to 64 (--jobs), normally 4 |
GRITPACK_ERROR_FORMAT | human or json errors (--error-format) |
GRITPACK_PAGER, PAGER | The pager |
GRITPACK_ADMIN_PROFILE | The administrator profile (admin --profile) |
NO_COLOR | When set, help and errors have no colour |
CI | When set, Gritpack never prompts |
gritpack help environment prints the full list. Two of them are worth a
word:
GRITPACK_HOMEmoves everything at once: logins, credentials, cache, installed applications, aliases. Point it at an empty directory to try something without touching your real setup.FROGFISH_HOMEmoves the parent directory instead, and Gritpack uses itsgritpackfolder.GRITPACK_PROFILEis handy in a shell where you work on one hub all day:export GRITPACK_PROFILE=workand 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.