lua governance

lua governance creates a governance.ts policy file for the agent in SDK or API mode, or removes it and clears governance on the server. The policy takes effect for end users only after you push the agent and promote a version; what a policy enforces is described in About governance. Verified against lua-cli 3.33.0.

Synopsis

lua governance
lua governance add
lua governance remove

Description

add, which is also what a bare lua governance runs, is an interactive wizard; it takes no flags and cannot be driven from --ci. It asks for the mode, then writes src/governance.ts (or ./governance.ts when the project has no src/ directory), asking governance.ts already exists. Overwrite? first if the file is present. In SDK mode it lists the tool names from the compiled manifest so you can pick the tools to block and the tools that need approval before running; run lua compile first, or the file gets an empty rules block. In API mode it asks for the governance server URL (default https://api.heygovernance.ai); the generated file reads GOVERNANCE_API_URL at runtime, and the API key is read from the GOVERNANCE_API_KEY environment variable, which you set with lua env production -k GOVERNANCE_API_KEY -v <key> and never commit. add writes only the policy file and needs no credential. The wizard does not edit your agent. Import the exported governance object in src/index.ts, pass it as the governance field of LuaAgent, then lua compile and lua push agent (or lua push all). Governance is pushed only when the compiled agent defines it, so a project without the file never clears a server-side policy. lua sync reports governance drift, and lua sync --pull writes an organization-set policy into src/governance.ts and wires the import for you. remove asks for confirmation, deletes the local governance.ts if it exists, and clears governance on the server; it clears the server even when there is no local file. Afterwards remove the import and the governance field yourself, then lua compile and lua push. remove needs a project and a credential, and it exits 0 even when the server clear fails; watch for ❌ Failed to clear governance on server.

Arguments

Argument	Values	Description
`[action]`	`add`, `remove`	Defaults to `add`. Aliases: `create` and `new` for `add`; `rm`, `delete`, and `del` for `remove`.

Options

None beyond the global -h, --help. Every choice is made in the wizard.

Examples

Scaffold a policy after compiling, so the wizard can list your tools:

lua compile
lua governance add

The SDK-mode file the wizard writes, with one blocked tool and one that needs approval:

src/governance.ts

/**
 * Governance Policy (SDK mode)
 * Policies are enforced locally at the platform level.
 * Import this into your LuaAgent config.
 */

export const governance = {
  mode: 'sdk' as const,
  rules: {
    blockTools: ['delete_ticket'],
    requireToolApproval: ['issue_refund'],
  },
};

Wire it into the agent:

src/index.ts

import { LuaAgent } from 'lua-cli';
import { governance } from './governance';
import tickets from './skills/TicketsSkill';

export default new LuaAgent({
  name: 'helpdesk-triage',
  persona: 'You triage support tickets for Acme.',
  governance,
  skills: [tickets],
});

Push the agent so the policy reaches the server, then promote a version:

lua compile
lua push agent --force
lua version create -m "Add governance"
lua version promote <n>

Remove the policy locally and on the server:

lua governance remove

Exit codes

Code	Meaning
`0`	File written, policy removed, or the wizard was aborted. Also when `remove` could not clear the server.
`1`	Under `--ci`, the wizard cannot prompt.
`2`	Unknown action, or `remove` outside a project.
`9`	`remove` without a credential, or the server rejected it.

SDK

CLI

REST API

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Options

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also