bundle add envless-envenvless-env is required as envless/env, runs on Ruby 3.2 and newer, and depends on envless-sdk and nothing else. It ships RBS signatures for every method below, so Steep checks your calls with library "envless-sdk", "envless-env" in your Steepfile.
require "envless/env"
| Method | Signature |
|---|---|
Envless::Env.load | (revalidate: false) -> Hash[String, String] |
Envless.env | The strict view of every variable, coerced. Also Envless::Env.values |
Envless::Env.optional | The same view, nil for a name that is not set. Also Envless.env.optional |
Envless::Env.client | Client variables only. Also Envless.env.client |
Envless::Env.override | (Hash values) { ... }, or without a block a handle with restore |
Envless::Env.fetch_environment | (token:, project:, environment:, product: nil, passphrase: nil, key: nil, workspace_id: nil, endpoint: nil, adapter: nil) -> Hash[String, String] |
Envless::Env::VERSION | The gem version |
The views
Envless.env, optional and client are views over one store, and each answers the same methods.
| Method | Behaviour |
|---|---|
[](name) | The value, coerced. name is a Symbol or a String |
fetch(name, default), fetch(name) { } | Like Hash#fetch: the default or the block when the name is not set |
key?(name) | Whether the name is set and visible in this view, without raising |
keys | The visible names, never the values |
optional, client | The view with that rule added, so Envless.env.client.optional works |
snapshot, to_h, to_json, as_json | Every visible value, coerced. Only on the client view; the others raise SerialisationError |
NAME | For a name that starts with a capital letter, Envless.env.DATABASE_URL reads like Envless.env[:DATABASE_URL]. Untyped, so prefer [] under Steep |
[]=(name, value) | Raises ReadOnlyError. Use Envless::Env.override |
require "envless/env/load"
Requires envless/env and calls Envless::Env.load, so a failed load raises from the require.
require "envless/env/rails"
Defines Envless::Env::Railtie, which calls Envless::Env.load in before_configuration and adds an envless helper to Action View returning Envless.env.client.snapshot. See Rails.
bundle exec envless-env types
Writes sig/envless-env.rbs, signatures that type Envless.env and its views by variable name. Flags: --output PATH, --project SLUG, --product SLUG, --env SLUGS and --check, which exits 1 when the file is stale and writes nothing. See Typed variables.
Crypto
| Method | Signature |
|---|---|
Envless::Env.encrypt | (plaintext, passphrase, workspace_unique_id) -> String |
Envless::Env.decrypt | (ciphertext, passphrase, workspace_unique_id) -> String |
Envless::Env.encrypt_with_key | (key, plaintext) -> String |
Envless::Env.decrypt_with_key | (key, ciphertext) -> String |
Envless::Env.workspace_key | (passphrase, workspace_unique_id) -> Envless::WorkspaceKey |
Envless::Env.import_workspace_key | (material) -> Envless::WorkspaceKey, base64url, 32 bytes |
Envless::Env.passphrase_strength | (passphrase) -> Envless::Validation |
Envless::Env::ENCRYPTION_PARAMETERS | The recipe's constants |
These are the Ruby SDK's functions under the names @goenvless/env uses, workspace_key being derive_workspace_key, and they are byte for byte compatible with the dashboard, the CLI and every other Envless package. Derive the key once with workspace_key when you handle more than one value, since encrypt and decrypt run the 200,000 iteration KDF on every call.
Errors
Every error inherits Envless::Env::Error, which inherits Envless::Error from envless-sdk, so one rescue Envless::Error catches anything Envless raises.
| Error | Raised when |
|---|---|
Envless::Env::LoadError | A load fails. See when a load fails. Not Ruby's ::LoadError |
Envless::Env::NotLoadedError | A read before the first load |
Envless::Env::MissingVariableError | A strict read of a name that is not set. variable names it |
Envless::Env::ServerOnlyError | A read of a server variable through the client view. variable names it |
Envless::Env::ReadOnlyError | Assigning a name on a view |
Envless::Env::SerialisationError | Dumping or marshalling a view other than the client view |