Environment Variables

The env module reads and updates environment variables exposed by the runtime.

This is an API reference. Its snippets are isolated operations and assume the named variables and security policies already exist.

Variables must be defined in the Environment System before they can be accessed. The system controls which storage backends (OS, file, memory) provide values and whether variables are read-only.

Loading

local env = require("env")

get

Retrieve an environment variable.

-- Get database connection string
local db_url = env.get("DATABASE_URL")
if not db_url then
    return nil, errors.new({ kind = errors.INVALID, message = "DATABASE_URL not configured" })
end

local port, port_err = get_or("PORT", "8080")
if port_err then return nil, port_err end

Returns: string, error

The function returns nil, error when the variable does not exist.

set

Set an environment variable.

-- Set runtime configuration
local updated, set_err = env.set("APP_MODE", "production")
if set_err then return nil, set_err end
return updated

Returns: boolean, error

get_all

Retrieve all environment variables accessible to the caller.

local logger = require("logger")

local vars, vars_err = env.get_all()
if vars_err then return nil, vars_err end

-- Log names only. Values such as connection URLs may contain credentials even
-- when their keys do not include words like SECRET or KEY.
local accessible_keys = {}
for key in pairs(vars) do table.insert(accessible_keys, key) end
logger:debug("accessible environment variables", {keys = accessible_keys})

-- Check required variables
local required = {"DATABASE_URL", "REDIS_URL", "API_KEY"}
for _, key in ipairs(required) do
    if not vars[key] then
        return nil, errors.new({ kind = errors.INVALID, message = "Missing required env var: " .. key })
    end
end

Returns: table, error

Permissions

Security policy evaluation applies to environment access.

Security Actions

get_all has no dedicated security action: it returns only the variables for which the env.get action is permitted, filtering each variable name through env.get.

Checking Access

local security = require("security")

if security.can("env.get", "DATABASE_URL") then
    local url = env.get("DATABASE_URL")
end

See Security Model for policy configuration.

Errors

See Error Handling for working with errors.

See Also

• Environment System - Configure storage backends and variable definitions