installation.mdx

title	Installation
description	Install the elizaOS CLI and scaffold your first project or plugin.

The public elizaos package installs the elizaos binary. The CLI is small on purpose: it creates and upgrades generated workspaces, shows template information, and prints versions. Running, building, and testing happens through scripts inside the generated project or plugin.

Prerequisites

• Node.js 24+: install from nodejs.org or use a version manager.
• Bun: install from bun.sh. Generated TypeScript workspaces use Bun scripts.
• Git: required when creating a project template that includes the local eliza checkout.

**Windows users:** WSL2 is the recommended shell for project development.

Install the CLI

You can run the CLI without a global install:

npx elizaos@beta

Or install it globally:

bun add -g elizaos@beta

Verify the installed binary:

elizaos --version
elizaos version

The npm package name is `elizaos`, and the binary is `elizaos`.

Create a project

Create a deployable product workspace:

elizaos create my-agent-app --template project
cd my-agent-app
bun install
bun run dev

The project template creates the app workspace, initializes the local eliza checkout unless you pass --skip-upstream, and writes .elizaos/template.json metadata so future template upgrades can be applied intentionally.

Useful project scripts are defined in the generated package.json:

bun run dev
bun run build
bun run test
bun run typecheck
bun run lint

Create a plugin

Create a runtime extension:

elizaos create plugin-weather --template plugin
cd plugin-weather
bun install
bun run build
bun run test

Plugins add runtime capabilities such as actions, providers, evaluators, services, routes, or app surfaces. They are consumed by projects after they are built and added as dependencies or local workspace packages.

Inspect templates

List available templates:

elizaos info
elizaos info --template project
elizaos info --template plugin
elizaos info --language typescript

For automation:

elizaos info --json

Upgrade generated files

Run upgrades from the root of a generated project or plugin:

elizaos upgrade --check
elizaos upgrade

The upgrade command reads .elizaos/template.json, renders the latest version of the same template, and updates managed files. Locally modified files that conflict are skipped and reported.

Troubleshooting

If a global install does not expose `elizaos`, make sure Bun's global bin directory is on your `PATH`:

```bash
export PATH="$HOME/.bun/bin:$PATH"
```

You can always use `npx elizaos@beta` without a global install.

npm `latest` still points at `elizaos@1.7.2`, whose bin shim imports a forbidden `@elizaos/cli` subpath. Pin the beta channel until `latest` is republished:

```bash
bun add -g elizaos@beta
# or
npx elizaos@beta --version
```

Check your Node.js version:

```bash
node --version
```

Use Node.js 24 or newer for the CLI and generated workspaces.

Preview before writing:

```bash
elizaos upgrade --check
```

If the command reports conflicts, review the listed files and apply the template changes manually where needed.

See also

Create and run a generated project. Commands, flags, and examples. Understand generated project structure. Build a reusable runtime extension.