> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Starter projects

> Create and manage API Performance starter projects from the Lightsage CLI.

Starter projects are repositories Lightsage can clone before running coding-agent API Performance evals. Use them when an eval should start inside a specific app, framework, SDK example, or integration fixture.

## Commands

| Command                                                                                         | Description                   |
| ----------------------------------------------------------------------------------------------- | ----------------------------- |
| `lightsage api-performance starter-projects list`                                               | List starter projects.        |
| `lightsage api-performance starter-projects create`                                             | Create a starter project.     |
| `lightsage api-performance starter-projects retrieve --starter-project-id <starter_project_id>` | Retrieve one starter project. |
| `lightsage api-performance starter-projects update --starter-project-id <starter_project_id>`   | Update one starter project.   |
| `lightsage api-performance starter-projects delete --starter-project-id <starter_project_id>`   | Delete one starter project.   |

## List starter projects

```bash theme={null}
lightsage api-performance starter-projects list
```

Filter to one source:

```bash theme={null}
lightsage api-performance starter-projects list --source-id source_123
```

Example response:

```json theme={null}
{
  "data": [
    {
      "id": "starter_123",
      "source_id": "source_123",
      "name": "Next.js starter",
      "repo_url": "https://github.com/acme/api-starter",
      "ref": "main",
      "subdir": "",
      "install_steps": ["pnpm install"],
      "framework": "nextjs",
      "enabled": true
    }
  ],
  "meta": {
    "count": 1
  }
}
```

## Create a starter project

```bash theme={null}
lightsage api-performance starter-projects create \
  --name "Next.js starter" \
  --repo-url "https://github.com/acme/api-starter" \
  --ref main \
  --framework nextjs \
  --install-steps "pnpm install"
```

Use `--subdir` when the app lives below the repository root:

```bash theme={null}
lightsage api-performance starter-projects create \
  --name "SDK examples" \
  --repo-url "https://github.com/acme/examples" \
  --subdir "examples/nextjs" \
  --framework nextjs
```

Supported framework values include `fastify`, `nuxt`, `express`, `spa-js`, `angular`, `react`, `fastapi`, `vite`, `nextjs`, and `custom`.

## Retrieve a starter project

```bash theme={null}
lightsage api-performance starter-projects retrieve --starter-project-id starter_123
```

## Update a starter project

```bash theme={null}
lightsage api-performance starter-projects update --starter-project-id starter_123 \
  --ref '"main"' \
  --enabled true
```

Updateable fields:

| Flag              | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `--name`          | Display name.                                                              |
| `--repo-url`      | Git repository URL.                                                        |
| `--ref`           | Branch, tag, or commit SHA.                                                |
| `--subdir`        | Directory to use after cloning.                                            |
| `--install-steps` | Install commands. Use a repeated flag on create or a JSON array on update. |
| `--source-id`     | Source ID this starter project applies to.                                 |
| `--framework`     | Framework hint.                                                            |
| `--enabled`       | Enable or disable the starter project.                                     |

## Delete a starter project

```bash theme={null}
lightsage api-performance starter-projects delete --starter-project-id starter_123
```