Configuration#

Most of the choices that HyperShell makes about timing, task bundling, coordination, logging, and such are configurable by the user. This configuration is loaded when HyperShell starts and is constructed from several sources including an ordered merger of files, environment variables, and command-line options.

In order of precedence (lowest to highest), three files are loaded:

Level	BSD/Linux	Windows
System	`/etc/hypershell.toml`	`%ProgramData%\HyperShell\Config.toml`
User	`~/.hypershell/config.toml`	`%AppData%\HyperShell\Config.toml`
Local	`./.hypershell/config.toml`	`.\.hypershell\Config.toml`

The TOML format is modern and minimal.

Every configurable option can be set in one of these files. Further, every option can also be set by an environment variable, where the name aligns to the path to that option, delimited by underscores.

For example, set the logging level at the user level with a command:

Set user-level configuration option

hyper-shell config set logging.level info --user

The file should now look something like this:

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

Alternatively, you can set an environment variable and the runtime configuration would be equivalent:

Define environment variable

export HYPERSHELL_LOGGING_LEVEL=INFO

Finally, any option defined within a configuration file that ends with _env or _eval is automatically expanded by the given environment variable or shell expression, respectively. This is useful as both a dynamic feature but also as a means to obfuscate sensitive information, such as database connection details.

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

[database]
provider = "postgres"
database = "hypershell"
host = "my.instance.university.edu"
user = "me"
password_eval = "pass hypershell/database/password"  # Decrypt using GNU Pass

Parameter Reference#

[logging]

Logging configuration. See also logging section.

.level: One of DEVEL, TRACE, DEBUG, INFO, WARNING, ERROR, or CRITICAL (default: WARNING)
.datefmt: Date/time format, standard codes apply (default: ‘%Y-%m-%d %H:%M:%S’)
.format: Log message format. Default set by the default logging.style. See the available attributes defined by the underlying Python logging interface.
.style: Presets for logging.format which can be difficult to define correctly. Options are default, detailed, and system.

[database]

Database configuration and connection details. See also database section.

.provider

Database provider (default: ‘sqlite’). Supported alternatives include ‘postgres’ (or compatible). Support for other providers may be considered in the future.

.file

Only applicable for SQLite provider. SQLite does not understand any other connection detail.

.database

Name for database. Not applicable for SQLite.

.schema

Not applicable for all RDMS providers. For PostgreSQL the default schema is public. Specifying the schema may be useful for having multiple instances within the same database.

.host

Hostname or address of database server (default: localhost).

.port

Port number to connect with database server. The default value depends on the provider, e.g., 5432 for PostgreSQL.

.user

Username for databaser server account. If provided a password must also be provided. Default is the local account.

.password

Password for database server account. If provided a user must also be provided. Default is the local account.

Task Environment#

A few common environment variables are defined for every task.

TASK_ID: Universal identifier (UUID) for the current task.
TASK_ARGS: Original input command-line argument line. Equivalent to {}, see templates section.
TASK_SUBMIT_ID: Universal identifier (UUID) for submitting application instance.
TASK_SUBMIT_HOST: Hostname of submitting application instance.
TASK_SUBMIT_TIME: Timestamp task was submitted.
TASK_SERVER_ID: Universal identifier (UUID) for server application instance.
TASK_SERVER_HOST: Hostname of server application instance.
TASK_SCHEDULE_TIME: Timestamp task was scheduled by server.
TASK_CLIENT_ID: Universal identifier (UUID) for client application instance.
TASK_CLIENT_HOST: Hostname of client application instance.
TASK_COMMAND: Final command line for task.
TASK_ATTEMPT: Integer number of attempts for current task (starts at 1).
TASK_PREVIOUS_ID: Universal identifier (UUID) for previous attempt (if any).
TASK_CWD: Current working directory for the current task.
TASK_OUTPATH: Absolute file path where standard output is directed (if defined).
TASK_ERRPATH: Absolute file path where standard error is directed (if defined).

Further, any environment variable starting with HYPERSHELL_EXPORT_ will be injected into the task environment sans prefix; e.g., HYPERSHELL_EXPORT_FOO would define FOO in the task environment. You can also define such variables in the export section of your configuration file(s); e.g.,

~/.hypershell/config.toml

# File automatically created on 2022-07-02 11:57:29.332993
# Settings here are merged automatically with defaults and environment variables

[logging]
level = "info"

# Options defined as a list will be joined with a ":" on BSD/Linux or ";" on Windows
# Environment variables will be in all-caps (e.g., FOO and PATH).
[export]
foo = "value"
path = ["/some/bin", "/some/other/bin"]