Help topics

Environment variables, exit codes, JSON output and where logins are kept: gritpack help <topic>.

Generated from gritpack help <topic>Gritpack 1.2.63

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.