> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Project Setup

> Initialize and configure a project for Islo with islo init and islo add.

`islo init` and `islo add` are the two commands that create and edit `islo.yaml` for you. Use `init` once to scaffold the file, then `add` to append setup steps as you bring more tools into the project.

For the full file schema, see [islo.yaml](/configuration/islo-yaml/). For how setup scripts execute inside the sandbox, see [Setup Scripts](/concepts/tools-lifecycle/).

## islo init

Scaffold a new `islo.yaml` in the current directory.

```bash
islo init [options]
```

| Option                  | Description                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `-t, --template <name>` | Use a built-in template (see [Templates](#templates)). Omit for an interactive wizard. |
| `--list`                | Print the available templates and exit.                                                |
| `-f, --force`           | Overwrite an existing `islo.yaml`.                                                     |

**Examples:**

```bash
islo init                          # Interactive wizard
islo init --template python        # Start from the Python template
islo init --template node --force  # Replace an existing islo.yaml
islo init --list                   # List templates
```

The wizard inspects the current directory and proposes setup steps for the languages and tools it finds, then writes the resulting `islo.yaml`. If the file already exists, `init` refuses to overwrite unless you pass `--force`.

### Templates

| Template    | Aliases                      | What you get                                              |
| ----------- | ---------------------------- | --------------------------------------------------------- |
| `default`   | –                            | A commented-out starter `islo.yaml` with all fields shown |
| `python`    | `py`                         | uv install + `uv sync`                                    |
| `node`      | `nodejs`, `js`, `javascript` | `corepack enable` + `pnpm install --frozen-lockfile`      |
| `rust`      | `rs`                         | Empty starter (add Cargo steps with `islo add`)           |
| `go`        | `golang`                     | Empty starter (add Go steps with `islo add`)              |
| `fullstack` | `full-stack`, `full`         | pnpm + uv (frontend + Python backend)                     |

Run `islo init --list` to see the live list — new templates may have been added since.

## islo add

Append setup steps to `islo.yaml`. Each invocation writes one or more entries under [`setup_scripts:`](/configuration/islo-yaml/#setup_scripts).

```bash
islo add [tool] [version] [options]
```

| Argument / Option      | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `tool` (positional)    | Recipe name (e.g., `python`, `node`). Omit to detect tools interactively. |
| `version` (positional) | Version to install. Omit to use the recipe's default.                     |
| `--script <text>`      | Add a custom shell snippet instead of looking up a recipe.                |

**Examples:**

```bash
islo add                                       # Interactive: detect tools, pick which to add
islo add python 3.12                           # Python 3.12 via the built-in recipe
islo add node 20                               # Node 20 via the built-in recipe
islo add --script 'apt-get install -y curl'   # Append a one-off custom step
```

The interactive flow (`islo add` with no args) scans the project for signals — lockfiles, manifests, version files — and shows a checklist of recipes you can enable. Pick the ones you want and Islo writes the entries.

### Built-in recipes

`islo add <name>` knows recipes for the following:

**Languages:** `python`, `node`, `go`, `rust`, `ruby`, `java`

**Package managers and build tools:** `uv`, `poetry`, `pip`, `pnpm`, `yarn`, `npm`, `bundler`, `cargo`, `go-modules`

**Services:** `docker-compose`

**Agent CLIs:** `claude-code`, `codex`, `gemini-cli`, `cursor-cli`, `copilot-cli`, `doubleagent`

**Other CLIs:** `gh`, `ripgrep`, `fd`, `jq`

For anything not in the registry, use `--script` to add the install commands directly.

### Custom scripts

`--script` is the escape hatch when no recipe fits:

```bash
islo add --script 'apt-get update && apt-get install -y postgresql-client'
```

The text is added verbatim as a new step under `setup_scripts:`. Edit the entry in `islo.yaml` afterwards if you want to rename it or split it across multiple lines.

## Workflow

A typical project bootstrap:

```bash
islo init --template python    # Scaffold islo.yaml
islo add poetry                # Add Poetry on top of the Python recipe
islo add --script './scripts/seed-db.sh'
islo use my-project            # Create the sandbox; setup steps run
```

After this point, `islo.yaml` is just a normal file in your repo — edit it directly when you outgrow the recipes.