# Project setup

> Set up an Elide project with elide.pkl: `elide init` templates, named scripts, dependencies, workspaces, and pinning the Elide version.

A project is a directory with an `elide.pkl`. Outputs, dependencies, reports and build state go in `.dev/`. Run
commands from the project directory, or pass `-p PATH`.

See [The .dev directory](https://elide.help/docs/toolchain/development-directory) for generated files, workspace paths and cleanup.

```bash
elide init --templates   # android, java, ktjvm, spring, micronaut, web-simple, web-demo, workspace
```

## Create a project without prompts

`elide init` opens an editor in a terminal. In scripts and CI, pass `--plain --skip-defaults`, a template and its
parameters as `name=value`:

```bash
elide init --template java --parameters          # list parameters and blocks
elide init --template java --parameters --json   # the same, as JSON
elide init --plain --skip-defaults --skip-run --template java \
  project_name=greeter package=dev.acme greeting="Hi there" tests=false
```

```text
elide.pkl
src/main/dev/acme/Hello.java
```

| Argument | Effect |
| --- | --- |
| `NAME=VALUE` or `NAME VALUE` | Sets a parameter; omitted parameters take their defaults. |
| `BLOCK=true`, `BLOCK=false` | Turns an optional block on or off: `tests` (test sources), `mcp` (`.mcp.json`). |
| `--skip-run` | Does not run Elide after generating files. |
| `--overwrite` | Replaces existing files. |

| Input | Result |
| --- | --- |
| No terminal, without `--plain --skip-defaults` | Exit `2`: `` `elide init` needs an interactive terminal. `` |
| A value that fails validation | Exit `2`: `Parameter "package" value "1bad" validation failed with error: "Not a valid Java package name."` |
| A block value other than `true`/`false` | Exit `2`: `Could not parse block "tests" value "maybe" as boolean, it must be true or false` |
| An unknown name | Warning `No parameter or block "colour" exists, value "red" will be ignored`; exit `0` |

## Create a JVM project

```pkl
amends "elide:project.pkl"

name = "hello"

jvm {
  main = "sample.HelloKt"
}
```

`src/main/kotlin/sample/Hello.kt`:

```kotlin
package sample

fun main() {
  println("Hello from Kotlin")
}
```

```bash
elide install
elide build
elide run
```

`src/main/kotlin` needs no `sources` block; see [Source Sets](https://elide.help/docs/toolchain/source-sets).

<img src="https://elide.help/assets/demos/project-build.gif" alt="Building and running a Kotlin project with Elide" width="1591" height="910" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`elide build --inspect` lists the tasks and their options; see [Build Tasks](https://elide.help/docs/toolchain/build-tasks).

## Add a script

```pkl
scripts {
  ["greet"] = "echo hello"
}
```

```bash
elide run greet
```

Scripts run under `/bin/sh`. `elide run NAME` picks the first match: a file, then `elide.pkl` scripts, then
`package.json` or `pyproject.toml` scripts, then `node_modules/.bin`.

## Add dependencies

Declare Maven, npm and PyPI packages under `dependencies`; `elide install` resolves Maven and npm packages, not PyPI
([Python packages](https://elide.help/docs/python-packages)). See [Dependencies](https://elide.help/docs/toolchain/dependencies) and the
[reference](https://elide.help/docs/elide-pkl-reference#dependencies).

## Create a workspace

A workspace root lists member projects and builds them as one task graph. `elide init --template workspace` creates
one. See [Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

## Inspect a project

```bash
elide project info                 # resolved source sets, dependencies, artifacts
elide project advice               # usage advice for coding agents
elide project export               # the resolved manifest as JSON
elide project export --format=pom  # or intellij
elide classpath                    # the main compile classpath, `:`-separated
elide classpath test:runtime       # [<source-set>:]<usage>
```

`-f` flags change the export. Formats: [Project export formats](https://elide.help/docs/cli-references#project-export-formats).
Classpath usages: [Source Sets](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths).

## Pin the Elide version

```bash
elide use 1.6.0               # write .elideversion and install that version
elide use 1.6.0 --no-install  # only write the file
```

`toolchain.engines` in `elide.pkl` lists accepted versions; see [Toolchain](https://elide.help/docs/elide-pkl-reference#toolchain).