env

env(key) reads one environment variable as a string. Locally it resolves from your shell environment merged with the project’s .env file; in a deployed agent it resolves from the environment’s variable store that you manage with lua env. Available everywhere agent code runs, including workflow code steps, where ctx.env[key] reads the same values; process.env.KEY works too. Verified against lua-cli 3.33.0.

import { env } from 'lua-cli';

Quick example

Treat a missing secret as a configuration error.

import { env } from 'lua-cli';

const apiKey = env('WEATHER_API_KEY');
if (!apiKey) throw new Error('WEATHER_API_KEY is not set');

Functions

env(key, options?)

Returns the variable’s value, or undefined when it isn’t set.

env(key: string, options?: { manifest?: boolean }): string | undefined

string

required

The variable name, for example WEATHER_API_KEY.

boolean

Accepted for compatibility; the function ignores it.

Where the value comes from:

Run	Source
`lua test`	`process.env`, then `.env` in the project root; the file wins
Sandbox turn (`lua chat`)	The `.env` values uploaded with each sandbox version; there is no server-side sandbox store
Deployed, production	The production store: `lua env production -k <KEY> -v <value>`

Values are always strings; convert numbers and booleans yourself. Returns — the value, or undefined. Example

import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export default class GetWeatherTool implements LuaTool {
  name = 'get_weather';
  description = 'Current weather for a city';
  inputSchema = z.object({ city: z.string() });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const apiKey = env('WEATHER_API_KEY');
    if (!apiKey) throw new Error('WEATHER_API_KEY is not set');
    const baseUrl = env('WEATHER_API_URL') ?? 'https://api.example.com';
    const response = await fetch(`${baseUrl}/v1/current?q=${encodeURIComponent(input.city)}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    return (await response.json()) as { temperature: number; condition: string };
  }
}

Errors — none; a missing variable returns undefined.

env.template(key)

Returns a placeholder that a workflow definition resolves from the target agent’s environment at lua push, wherever a template(...) binding is accepted.

env.template(key: string): { __envRef: string }

string

required

The variable name. Names ending in SECRET, TOKEN, KEY, or PASSWORD are refused.

Returns — { __envRef: key }. It is never a value: read the variable with env(key) inside the step that needs it. Example

import { env } from 'lua-cli';

export const timezone = env.template('FINANCE_TZ');

Errors — env-template-secret-key: \API_KEY` looks like a secret — read it with env(‘API_KEY’) inside execute instead` for a secret-looking name.

env.template belongs in workflow files, which the compiler evaluates. In a deployed agent the runtime env has no template member (env.template is not a function), and in lua test it returns the placeholder without the secret-name check.

Types

string | { base?: string; voice?: string; text?: string }

The shape of persona on LuaAgent. A string is the whole persona; in object form base is always rendered, voice is appended on voice channels, and text on text channels.

SDK

CLI

REST API

Quick example

Functions

env(key, options?)

env.template(key)

Types

See also

​Quick example

​Functions

​env(key, options?)

​env.template(key)

​Types

​See also

Quick example

Functions

env(key, options?)

env.template(key)

Types

See also