Help topics
Environment variables, exit codes, JSON output and where logins are kept: gritpack help <topic>.
Run gritpack help <topic> to read one of these in a terminal.
environment
Environment variables Gritpack reads. gritpack help environment
Each one sets the default for the flag named beside it; a flag on the
command line wins.
Connecting to a hub
GRITPACK_SERVER the hub (--hub), as host[:port] or https://host
GRITPACK_PROFILE the login profile to use (--profile)
GRITPACK_CERT client certificate (--cert)
GRITPACK_KEY client private key (--key)
GRITPACK_CA certificate authority for the hub (--ca)
GRITPACK_ENROLLMENT_SERVER the hub `login` uses when none is named
GRITPACK_ENROLLMENT_CODE one-time code for `login` and `auth renew`
Where things are kept
GRITPACK_HOME Gritpack's own directory; default
~/.frogfish/gritpack
FROGFISH_HOME Frogfish directory; Gritpack uses its gritpack
folder when GRITPACK_HOME is unset
GRITPACK_CONFIG login profiles (--config); default
GRITPACK_HOME/config.toml
GRITPACK_CREDENTIALS_DIR credential files (--credentials-dir); default
GRITPACK_HOME/credentials
GRITPACK_CACHE_DIR downloaded packages (--cache-dir); default
GRITPACK_HOME/cache
GRITPACK_PACKAGES_DIR where a project's packages are installed
(--packages-dir)
Behaviour
GRITPACK_JOBS parallel downloads, 1 to 64 (--jobs); default 4
GRITPACK_ERROR_FORMAT human or json (--error-format)
GRITPACK_API_LISTEN address `gritpack api` listens on (--listen)
CI when set, Gritpack never prompts, and `login`
needs --store file or --store run
NO_COLOR when set, help and errors have no colour
GRITPACK_PAGER, PAGER the pager for long output on a terminal (info,
search, admin audit-log); default less; empty
or cat turns it off
Hub administration
GRITPACK_ADMIN_PROFILE administrator profile to use (admin --profile)
GRITPACK_ADMIN_CONFIG administrator profiles; default
GRITPACK_HOME/admin.toml
GRITPACK_MANAGEMENT_SERVER the hub's management address (admin --hub)
GRITPACK_ADMIN_CERT administrator certificate (admin --cert)
GRITPACK_ADMIN_KEY administrator private key (admin --key)
exit-codes
What each exit code means. gritpack help exit-codes
0 success
2 usage: wrong arguments, configuration or request
3 authentication: the hub did not accept your credential
4 authorization: your account may not do this
5 not found: no such package, version, login or installed item
6 conflict: something already there disagrees with the request
7 integrity: a package, lock file or answer failed its checks
8 unavailable: the hub or network could not be reached; try again
9 local I/O: a file or directory could not be read or written
70 internal: Gritpack could not finish safely
With --error-format json (or GRITPACK_ERROR_FORMAT=json), a failure is one
JSON object on stderr, with schema "gritpack/error@1" and stable `code`,
`category` and `exit_code` fields. Branch on those, not on the message.
formatting
JSON output, and how to script Gritpack. gritpack help formatting
Results go to stdout and messages to stderr, so a pipe gets only the result.
--format json a command's result as JSON, where the command offers it
--json the same as --format json
--json=a,b only those fields of each record; an unknown name lists
the fields there are
--jq EXPRESSION the JSON through a jq expression; strings print bare
--format ndjson one JSON object per line, for streaming (publish, search)
--error-format json
a failure as one JSON object on stderr
Human output may change between releases; JSON output keeps its schema.
Scripts should ask for JSON and read named fields.
Gritpack never prompts when stdin is not a terminal or CI is set. Commands
that would ask take --yes instead.
A published version can be named as name@version wherever a storage ID is
asked for, and an account by its email wherever an account ID is.
$ gritpack search parser --json=name,latest_version
$ gritpack search parser --jq '.results[].name'
$ gritpack sync --jq '.packages[] | .name + "@" + .version'
$ gritpack package yank @frogfish/parser@1.2.0
Long output on a terminal goes through a pager; `gritpack help environment`
says how to choose it. `gritpack alias set` gives a long command a short
name of your own.
profiles
Where logins and settings are kept. gritpack help profiles
`gritpack login` enrolls this computer with a hub and saves a login profile.
Commands use the default profile unless you pass --profile, or --hub with a
certificate.
~/.frogfish/gritpack/config.toml login profiles (GRITPACK_CONFIG)
~/.frogfish/gritpack/credentials/ certificates and keys kept as files
~/.frogfish/gritpack/admin.toml administrator profiles, which name the
administrator's certificate files
~/.frogfish/gritpack/aliases.toml your aliases (`gritpack alias`)
macOS Keychain credentials kept with --store keychain
run credentials kept in the run secret store
$ gritpack auth list your logins
$ gritpack auth use work make `work` the default
$ gritpack auth status check the login and show your account
$ gritpack auth renew replace a credential before it expires
$ gritpack auth migrate --store file move a credential to another store
$ gritpack auth logout revoke and forget a login
Administrator commands take --profile too, for a connection saved with
`gritpack admin profile add`; flags given on the command line win.
GRITPACK_HOME or FROGFISH_HOME moves the whole directory.