> ## 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 agents and lua models

> List the organizations and agents your credential can reach, and list, set, or clear the agent's model

`lua agents` lists every [organization](/concepts/credentials) and agent your credential can reach, so you can find an agent id for `lua init` or check access. `lua models` lists the [model](/concepts/models) catalog your organization may use and sets or clears the model of the configured agent; `set` and `unset` change the agent on the server and in `src/index.ts`.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua agents [--json]
lua models [list] [--json]
lua models set [--model <code>]
lua models unset
```

## Description

`lua agents` needs a credential but not a project. It walks every organization the credential can see, ten at a time, and pages through each organization's agents 100 at a time, so on an account with many organizations it takes tens of seconds. An API-key credential that can see more than 100 organizations is refused with `Lua CLI can request at most 100 organizations at once.`; a user session has no such cap. The text view marks the organization from `lua.skill.yaml` with `⭐` and the configured agent with `← current`, and ends with `Total: <n> organization(s)`.

`lua models` without an action runs `list`, which fetches the catalog the server allows for your organization and prints it grouped by provider, marking the agent's current model or `(platform default)`. It works outside a project; then no current model is shown. `set` validates `--model` against the catalog, writes `model: '<code>'` into the `new LuaAgent({ … })` call in `src/index.ts`, and updates the agent on the server; without `--model` it opens a picker. If the server rejects the model for your organization, the code is already in your source but not applied, and the command says so. `unset` removes `model` from the source and clears it on the server, so the platform default applies. `set` and `unset` require a project. Action aliases: `ls` and `l` for `list`; `select` and `use` for `set`; `clear`, `reset`, and `remove` for `unset`.

## Arguments

| Argument   | Values                 | Description                            |
| ---------- | ---------------------- | -------------------------------------- |
| `[action]` | `list`, `set`, `unset` | `lua models` only. Defaults to `list`. |

## Options

| Option           | Description                                                             | Default |
| ---------------- | ----------------------------------------------------------------------- | ------- |
| `--json`         | `lua agents`, `lua models list`: print JSON.                            | off     |
| `--model <code>` | `lua models set`: model code such as `openai/gpt-4o`; skips the picker. | picker  |

## Output

`lua agents --json` prints an array of organizations. `name` is omitted when an organization or agent has none; `visibility` is `private`, `public`, or `platform`; `discoveredVia` is `org-grant` or `agent-grant-only`; `displayRoles` lists `{ role, boundTo, resourceId }` for roles you hold. Trimmed to one organization:

```json Output theme={null}
[
  {
    "orgId": "org_…",
    "name": "Claude Plugin E2E",
    "archived": false,
    "discoveredVia": "org-grant",
    "agents": [
      {
        "agentId": "agent_…",
        "name": "Designer",
        "visibility": "public",
        "displayRoles": []
      },
      {
        "agentId": "agent_…",
        "name": "helpdesk-triage",
        "visibility": "private",
        "displayRoles": [
          {
            "role": "admin",
            "boundTo": "agent",
            "resourceId": "agent_…"
          }
        ]
      }
    ]
  },
  …
]
```

`lua models list --json` prints `{ currentModel, models }`; `currentModel` is `null` when the platform default applies. Each model carries `provider`, `code`, `model`, `displayName`, `description`, `reasoning`, `media`, `tools`, `promptCache`, and `actionMultiplier`. The catalog changes server-side; read it rather than copying it. Trimmed to one model:

```json Output theme={null}
{
  "currentModel": "alibaba/qwen3.8-flash",
  "models": [
    {
      "provider": "alibaba",
      "code": "alibaba/qwen3-vl-plus",
      "model": "qwen3-vl-plus",
      "displayName": "Qwen3-VL Plus",
      "description": "Qwen3 VL Plus — vision-language model for image + video understanding (256K context)",
      "reasoning": {
        "supported": true,
        "adaptive": false,
        "efforts": [
          "off"
        ],
        "toggleOnly": true,
        "platformDefault": "on"
      },
      "media": {
        "image": true,
        "documents": false,
        "audio": false,
        "video": false
      },
      "tools": {
        "webSearch": "bridge"
      },
      "promptCache": {
        "mode": "automatic",
        "minimumCacheTokens": 1024
      },
      "actionMultiplier": 0.67
    },
    …
  ]
}
```

## Examples

Find the id of an agent to use with `lua init`:

```bash theme={null}
lua agents --json | jq -r '.[].agents[] | "\(.agentId)  \(.name)"'
```

Check that a CI credential can reach the agent it is about to push to:

```bash theme={null}
lua agents --json --ci | jq -e --arg id "$AGENT_ID" '.[].agents[] | select(.agentId == $id)'
```

List the model codes you may use:

```bash theme={null}
lua models list --json | jq -r '.models[].code'
```

Switch the agent to a model without a prompt, then return to the platform default:

```bash theme={null}
lua models set --model anthropic/claude-sonnet-5
lua models unset
```

## Exit codes

| Code | Meaning                                                                                                |
| ---- | ------------------------------------------------------------------------------------------------------ |
| `0`  | Listed, set, or cleared, including `No model is currently set`.                                        |
| `1`  | More than 100 organizations on an API-key credential, or `No models are currently available` on `set`. |
| `2`  | `set` or `unset` outside a project (`No agent configured.`), or an unknown action.                     |
| `9`  | No credential, the server rejected it, or `lua agents` may not read an organization's agents.          |
| `10` | `lua models`: the credential may not read the catalog.                                                 |
| `11` | The server or network is unavailable.                                                                  |

## See also

* [About models](/concepts/models) — choosing a model code and `modelSettings`
* [About credentials](/concepts/credentials) — what a credential can see
* [`lua init`](/reference/cli/init) — `--agent-id` and `--model`
* [`LuaAgent`](/reference/sdk/luaagent) — the `model` field `set` writes