Skip to main content
lua init writes a project scaffold into the current directory and binds it to an agent. Creating or duplicating an agent changes the platform; binding to an existing one changes nothing on the server. Verified against lua-cli 3.33.0.

​
Synopsis

​
Description

Without flags the command is interactive: it asks whether to use an existing agent, create one, or duplicate one, then which organization and agent; with a scoped key it skips the choice and offers existing agents only. With --agent-id, --agent-name, or --from-agent-id it runs without prompts. --ci does not stop the mode question; pass one of those three flags. In an empty directory it copies the scaffold and fills in the agent: src/index.ts with a LuaAgent whose name, persona, and model come from the agent, lua.skill.yaml with agentId and orgId, package.json, tsconfig.json, .gitignore, env.example, README.md, and QUICKSTART.md. --with-examples adds an examples/ directory of skills, tools, webhooks, jobs, processors, and workflows that are not registered on the agent. It then runs npm install --force; an install failure is a warning. For an existing agent it first looks for a source backup. When one exists, the files are restored into the directory, the scaffold’s src/ is skipped, and the agent’s name, persona, and model are synced from the server into src/index.ts. A restore that would overwrite files in the directory asks first unless --restore-sources is set, so pass it in automation. With no backup the command says so and continues with the scaffold. --from-agent-id creates a new agent from an existing one: skills, persona, model, and the project backup are copied, and the --include-* flags add resources and knowledge, custom data, inquiry forms, devices with their triggers, and the commerce catalog. --agent-name names the copy; --org-id or --org-name places it in another organization. Duplicating requires admin access to the source agent’s organization. --model is checked against the organization’s approved list before anything is created; an unknown code fails with Unknown model '<code>'. and the available codes. For an existing agent whose model differs, the chosen model is set on the server. A create under --ci without --model does not fail: the agent is created with no model of its own and answers with the platform default until you set one with lua models set --model <code> or a model on the LuaAgent followed by lua push agent. To find an agent id for --agent-id, run lua agents --json --ci. When the directory already holds a lua.skill.yaml with an agentId, a non-interactive run exits 2 with Project already initialized with agent <id> unless --force is given. With --force it rebinds: agentId and orgId are rewritten and the LuaAgent in src/index.ts is updated, without copying files or installing. Interactively it offers to keep or switch the agent. A scoped API key can bind to an existing agent but cannot create or duplicate one: those modes exit 10 with Scoped CLI credentials cannot create a new agent. or Scoped CLI credentials cannot duplicate an agent. Sign in with email, or create the agent in the admin dashboard and pass --agent-id.

​
Arguments

None. The mode is chosen by flags.

​
Options

--agent-id cannot be combined with --agent-name, --org-id, --org-name, or --from-agent-id; --org-id and --org-name are mutually exclusive; --org-id or --org-name alone requires --agent-name. Each violation exits 2 with the usage block.

​
Examples

Bind an empty directory to an agent you already have, restoring its backup when one exists:
Create a new agent in an existing organization with a chosen model:
Output
Create the agent and its organization together:
Duplicate an agent into another organization, including its knowledge:
Point an existing project at a different agent:

​
Exit codes

​
See also