> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# lua governance

> Scaffold the agent's governance policy file, or remove it and clear the policy on the server

`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](/concepts/governance).

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
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`](/reference/cli/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>`](/reference/cli/env) 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`](/reference/cli/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:

```bash theme={null}
lua compile
lua governance add
```

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

```ts src/governance.ts theme={null}
/**
 * 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:

```ts src/index.ts highlight={2,8} theme={null}
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:

```bash theme={null}
lua compile
lua push agent --force
lua version create -m "Add governance"
lua version promote <n>
```

Remove the policy locally and on the server:

```bash theme={null}
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.                                               |

## See also

* [About governance](/concepts/governance) — modes, presets, and what is enforced
* [`LuaAgent`](/reference/sdk/luaagent) — the `governance` field
* [`lua sync`](/reference/cli/sync) — governance drift and pulling an organization policy
* [`lua env`](/reference/cli/env) — where `GOVERNANCE_API_KEY` lives
* [`lua push`](/reference/cli/push)