@qui-cli/env

@qui-cli Plugin: Standardized environment configuration


Install

``sh
npm install @qui-cli/env
`

Usage

`ts
import { Env } from '@qui-cli/env';

// configure desired environment path
Env.configure({ path: '../../.env' });

// update .env
Env.set({ key: 'EXAMPLE', value: parseInt(process.env.EXAMPLE || '0') + 1 });
`

$3

Environment variables (from any .env file loaded by this plugin) are not available until after the Env.parse() has been called, which is not guaranteed to have occurred unless invoked directly by another plugin or _after_ the plugin has been initializied by init() (see dev-plugin-lifecycle for an illustration of this).

Any plugin that depends on this plugin can assume that the .env file environemnt variables are available in the dependent plugin's init() and run() methods, but will not be available in the dependent plugin's options() method and will only sometimes be available in the dependent plugin's configure() method (when it is invoked by init(), for example).

$3

To access 1Password secret references stored in the environment, install the optional peer dependency @1password/sdk. For full integration, also install the 1Password CLI which will allow you to look up a 1Password service account token by identifier.

The configuration options opToken, opItem, and opAccount may all be passed as command-line options. For example:

`sh
example --opToken "$(op item get ServiceAccountToken)"
`

If the 1Password CLI tool is installed, then opItem and opAccount can be used:

`sh
example --opAccount example.1password.com --opitem "My Token Identifier"
`

Configuration

`ts
export type Configuration = Plugin.Configuration & {
root?: string;
load?: boolean;
path?: string;
};
`

$3

Optional root for calculating relative paths to .env files. If undefined, falls back to the path defined by @qui-cli/root.

$3

Whether or not to load the .env file into process.env immediately. Defaults to true.

$3

Path to desired .env file relative to root. Defaults to '.env';

$3

If 1Password secret references are stored in the environment, a 1Password service account token is required to access the secret values.

#### opToken

1Password service account token; will use environment variable OP_TOKEN if present

#### opItem

Name or ID of the 1Password API Credential item storing the 1Password service account token; will use environment variable OP_ITEM if present. Requires the 1Password CLI tool.

#### opAccount

1Password account to use (if signed into multiple); will use environment variable OP_ACCOUNT if present

Options

When the optional peer dependency @1password/sdk is installed, Env exposes opAccount, opItem, and opToken as command-line options.

Initialization

Env loads the specified .env file into process.env.

API

`ts
import { Env } from '@qui-cli/env';
`

$3

Parse file (path relative to root, defaults to path if file is not defined) as a .env file and append to process.env. Passing load as true to configure() calls this immediately from configure().

$3

Determine if a particular key exists in the specified .env file (defaults path if file is not defined).

$3

Get the string value (if present) of a particular key in a .env file (defaults to path if file is not defined). Returns undefined if the key is not present.

$3

Set the value of a particular key in the specified .env file (defaults to path if file is not defined). Optional comment can be inserted preceding the key in the file.

$3

Remove a particular key from the specified .env file (defaults to path if file os not defined), optionally replacing the key with a comment`.