> ## 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 init > Create a project in the current directory and bind it to an existing, new, or duplicated agent `lua init` writes a [project scaffold](/get-started/project-structure) into the current directory and binds it to an [agent](/concepts/agents). 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 ```bash theme={null} lua init [--with-examples] [--model ] [--force] [--promo-code ] lua init --agent-id [--restore-sources] lua init --agent-name (--org-id | --org-name ) lua init --from-agent-id [--org-id | --org-name ] [--agent-name ] [--include-resources] [--include-custom-data] [--include-inquiry-form] [--include-devices] [--include-ecommerce-catalog] ``` ## 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 ''.` 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 ` 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 ` 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](/concepts/credentials) 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 | Option | Description | Default | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `--agent-id ` | Bind to this existing agent; `lua agents --json --ci` lists the ids you can see | prompt | | `--agent-name ` | Create an agent with this name; needs `--org-id` or `--org-name`. With `--from-agent-id`, the name of the copy | prompt | | `--org-id ` | Existing organization for the new or duplicated agent; `lua agents --json --ci \| jq -r '.[].orgId'` lists the ids you can see (see [`lua agents`](/reference/cli/agents-and-models)) | prompt | | `--org-name ` | Create an organization with this name for the new agent; with `--from-agent-id`, an existing organization matched by name | prompt | | `--from-agent-id ` | Duplicate this agent into a new one and restore its project backup | — | | `--include-resources` | Duplicate: copy resources and knowledge | off | | `--include-custom-data` | Duplicate: copy custom data | off | | `--include-inquiry-form` | Duplicate: copy inquiry forms | off | | `--include-devices` | Duplicate: copy device and device trigger definitions | off | | `--include-ecommerce-catalog` | Duplicate: copy the commerce catalog | off | | `--model ` | Model code such as `openai/gpt-4o`, validated against the organization's list | the agent's model, or prompt | | `--with-examples` | Copy the `examples/` directory | off | | `--restore-sources` | Overwrite existing files from the backup without asking | ask | | `--force` | Rebind a directory that already has a `lua.skill.yaml` | exit 2 | | `--promo-code ` | Apply a promo code when creating the agent | — | `--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: ```bash theme={null} mkdir helpdesk && cd helpdesk lua init --agent-id --restore-sources --ci ``` Create a new agent in an existing organization with a chosen model: ```bash theme={null} lua init --agent-name "Helpdesk" --org-id --model openai/gpt-4o --ci ``` ```text Output theme={null} ✅ Creating agent: Helpdesk ✅ Agent created successfully! … ✅ Lua skill project initialized successfully! ``` Create the agent and its organization together: ```bash theme={null} lua init --agent-name "Helpdesk" --org-name "Acme" --ci ``` Duplicate an agent into another organization, including its knowledge: ```bash theme={null} lua init --from-agent-id --org-id --include-resources --ci ``` Point an existing project at a different agent: ```bash theme={null} lua init --agent-id agent_def456 --force --ci ``` ## Exit codes | Code | When | | ---- | --------------------------------------------------------------------------------------------------------------------- | | `0` | Project created or rebound; a cancelled interactive run; a backup that could not be downloaded (the scaffold is used) | | `1` | Agent creation or duplication refused by the platform; unknown `--model` | | `2` | Invalid flag combination; existing project without `--force` | | `3` | `--agent-id`, `--org-id`, or `--org-name` not found; the hint lists what the credential can see | | `9` | No credential, or the platform refused it | | `10` | Scoped key used to create or duplicate an agent | | `11` | Platform or network unavailable | ## See also * [Quickstart](/get-started/quickstart) * [Project structure](/get-started/project-structure) * [lua.skill.yaml](/reference/cli/lua-skill-yaml) * [`lua pull`](/reference/cli/pull) — restore source into an existing project * [Backups and restore](/ship/backups-and-restore)