---
name: list-projects
description: List projects in the Tela workspace. Use when the user wants to see their projects, find a project, or needs project IDs.
---

# List Projects

List projects in the Tela API workspace.

## Usage

```bash
bun --preload ~/.claude/skills/tela-studio/preload.ts -e "console.log(JSON.stringify(await tela.listProjects({ limit: 1000 }), null, 2))"
```

## Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | number | `10` | Maximum number of projects to return |

**Always pass an explicit `limit` when you are searching for a project.** The default of `10` will
quietly hide the rest of the workspace: the response is a bare array with no `meta` and no
truncation marker, so a workspace with 33 projects looks exactly like a workspace with 10. Concluding
that a project does not exist — and creating a duplicate — is the usual result.

The limit is applied client-side after fetching every project, so a large `limit` costs no extra
requests.

## Response Type

```typescript
interface ProjectSummary {
  id: string          // UUID
  title: string       // Project name (max 256 chars)
  workspaceId: string // UUID of the workspace
}
```

`listProjects` returns only these three fields. Timestamps exist on the underlying record but are
stripped from the result — do not expect `createdAt` / `updatedAt` / `deletedAt` here.

`workspaceId` rarely needs to be passed around anymore: `createCanvas` infers it from the session
token, which is scoped to a single workspace. Pass it explicitly only when the credential carries
no workspace claim.

## Example Response

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Project",
    "workspaceId": "660e8400-e29b-41d4-a716-446655440001"
  }
]
```

## Finding a project by name

```bash
bun --preload ~/.claude/skills/tela-studio/preload.ts -e "
const projects = await tela.listProjects({ limit: 1000 })
const match = projects.filter(p => p.title.toLowerCase().includes('finance'))
console.log(match.length ? JSON.stringify(match, null, 2) : 'no match among ' + projects.length + ' projects')
"
```

Report the number of projects searched when nothing matches. If several match, ask the user which one
rather than picking the first.