# Projects

Use project commands to list projects, resolve project IDs, create projects, rename projects, and delete projects.

## Commands

List projects:

```bash
toggl --json projects list
```

Get one project:

```bash
toggl --json projects get --project-id <project-id>
```

Create a project:

```bash
toggl --json projects create --data '{"name":"Q3 Planning","private":true}'
```

When targeting a specific workspace, run `toggl --json workspace switch <workspace-id>` before the permissions check and create command; the project payload does not select the workspace.
When the user explicitly asks for a shared or public project, use `private: false` and skip the permissions check — only private projects require an entitlement.
Otherwise, before defaulting to a private project, run `toggl --json workspace-settings get-user-permissions`.
Use `private: true` when `permissions` includes `access_private_projects_tasks_feature`;
otherwise use `private: false` and tell the user. If the user explicitly requires privacy, do not create a shared project.
Omit `billable` unless billing was requested.

Rename a project:

```bash
toggl --json projects update --project-id <project-id> --payload-name "Q3 Planning"
```

Delete a project only after explicit user confirmation:

```bash
toggl --json projects delete --project-id <project-id> --yes
```

## Agent Workflow

When the user provides a project name, list projects and resolve the project ID before acting:

```bash
toggl --json projects list
```

When creating tasks, pass the resolved project ID to `tasks create`:

```bash
toggl --json tasks create --data '{"name":"Task name","project_id":123456}'
```

Project deletion is destructive. Confirm the exact project ID and name before using `--yes`.