> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doers.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Projects
> Projects and their progress.
5 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.
| Tool | What it does | Kind |
| ------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| [`list_projects`](#list_projects) | List the projects | Read · idempotent · no outside service |
| [`archive_project`](#archive_project) | Archive or restore a project | Write · destructive · no outside service |
| [`create_project`](#create_project) | Create a project | Write · no outside service |
| [`delete_project`](#delete_project) | Delete an archived project for good | Write · destructive · idempotent · no outside service |
| [`update_project`](#update_project) | Update a project | Write · idempotent · no outside service |
## list\_projects
**List the projects.**
Returns active and completed projects in manual order, with their task counts. Archived projects are excluded unless `includeArchived=true`.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/projects` |
| CLI | `doers projects list` |
| Touches | `projects`, `tasks` |
| Operation | `listProjects` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------------------- | ------- | -------- | ------- | ---------------- | ------------------------------------------------------------------ |
| `areaId` (query) | string | no | | UUID | Identifier of a row. |
| `status` (query) | string | no | | `active`, `done` | *No description in the registry.* |
| `includeArchived` (query) | boolean | no | `false` | | *No description in the registry.* |
| `workspaceId` (query) | string | no | | UUID | The workspace to read within; the personal one by default (T-D11). |
### Output
| Field | Type | Allowed values | Description |
| -------------------------- | ----------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `projects` | object\[] | | |
| `projects[].id` | string | | |
| `projects[].name` | string | | |
| `projects[].areaId` | string \| null | | |
| `projects[].status` | string | `active`, `done`, `archived` | |
| `projects[].deadline` | string \| null | | |
| `projects[].notes` | string | | |
| `projects[].order` | number | | Manual position. Fractional values are valid; lower sorts first. |
| `projects[].accessRole` | string (optional) | `owner`, `editor`, `commenter`, `reader` | Your effective role on this project. |
| `projects[].openTaskCount` | integer | -9007199254740991 to 9007199254740991 | |
| `projects[].doneTaskCount` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_projects",
"arguments": {
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"status": "active"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "- [244210e4-8437-4655-8980-a70249a99369] Acme · 3/6"
}
],
"structuredContent": {
"projects": [
{
"id": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"status": "active",
"deadline": "2026-09-22",
"notes": "Notes for the Acme launch.",
"order": 0,
"accessRole": "owner",
"openTaskCount": 3,
"doneTaskCount": 3
}
]
}
}
}
```
```bash CLI theme={null}
doers projects list --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf --status active
```
## archive\_project
**Archive or restore a project.**
Archiving is **reversible** and cascades to the project's open tasks. `restore: true` makes the project active again; its tasks are not unarchived automatically, matching the app.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Write · destructive · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `POST https://api.doers.sh/v2/projects/{projectId}/archive` |
| CLI | `doers projects archive` |
| Touches | `projects`, `tasks` |
| Operation | `archiveProject` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------------ | ------- | -------- | ------- | -------------- | --------------------------------- |
| `projectId` (path) | string | yes | | UUID | Identifier of a row. |
| `restore` | boolean | no | `false` | | *No description in the registry.* |
### Output
| Field | Type | Allowed values | Description |
| -------------------- | ----------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `project` | object | | |
| `project.id` | string | | |
| `project.name` | string | | |
| `project.areaId` | string \| null | | |
| `project.status` | string | `active`, `done`, `archived` | |
| `project.deadline` | string \| null | | |
| `project.notes` | string | | |
| `project.order` | number | | Manual position. Fractional values are valid; lower sorts first. |
| `project.accessRole` | string (optional) | `owner`, `editor`, `commenter`, `reader` | Your effective role on this project. |
| `archivedTasks` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "archive_project",
"arguments": {
"projectId": "244210e4-8437-4655-8980-a70249a99369",
"restore": false
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: project restored."
}
],
"structuredContent": {
"project": {
"id": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"status": "active",
"deadline": "2026-09-22",
"notes": "Notes for the Acme launch.",
"order": 0,
"accessRole": "owner"
},
"archivedTasks": 3
}
}
}
```
```bash CLI theme={null}
doers projects archive 244210e4-8437-4655-8980-a70249a99369 --restore false
```
## create\_project
**Create a project.**
Creates an active project, optionally attached to an area and with a deadline. A project with no area is filed under “No area”.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Write · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `POST https://api.doers.sh/v2/projects` |
| CLI | `doers projects create` |
| Touches | `projects`, `tasks` |
| Operation | `createProject` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------- | -------------- | -------- | ------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | yes | | 1 to 200 characters | *No description in the registry.* |
| `areaId` | string \| null | no | | UUID | *No description in the registry.* |
| `workspaceId` | string | no | | UUID | Where to file it: the personal workspace by default, or a team workspace the caller sits in. |
| `deadline` | string \| null | no | | `YYYY-MM-DD` | *No description in the registry.* |
| `notes` | string | no | | 0 to 10000 characters | Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (\`\`\`) or images**: the app's editor does not support them and truncates the display from that point on. |
### Output
| Field | Type | Allowed values | Description |
| -------------------- | ----------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `project` | object | | |
| `project.id` | string | | |
| `project.name` | string | | |
| `project.areaId` | string \| null | | |
| `project.status` | string | `active`, `done`, `archived` | |
| `project.deadline` | string \| null | | |
| `project.notes` | string | | |
| `project.order` | number | | Manual position. Fractional values are valid; lower sorts first. |
| `project.accessRole` | string (optional) | `owner`, `editor`, `commenter`, `reader` | Your effective role on this project. |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_project",
"arguments": {
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"deadline": "2026-09-22"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: project “Acme” created [244210e4-8437-4655-8980-a70249a99369]."
}
],
"structuredContent": {
"project": {
"id": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"status": "active",
"deadline": "2026-09-22",
"notes": "Notes for the Acme launch.",
"order": 0,
"accessRole": "owner"
}
}
}
}
```
```bash CLI theme={null}
doers projects create Acme --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf --deadline 2026-09-22
```
## delete\_project
**Delete an archived project for good.**
Removes a project permanently. **The project must already be archived**: the irreversible step is deliberately reachable only from the reversible one.
Its tasks are **detached, never deleted**: they lose their project and stay.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Write · destructive · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `DELETE https://api.doers.sh/v2/projects/{projectId}` |
| CLI | `doers projects delete` |
| Touches | `projects`, `tasks` |
| Operation | `deleteProject` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------------ | ------ | -------- | ------- | -------------- | -------------------- |
| `projectId` (path) | string | yes | | UUID | Identifier of a row. |
### Output
| Field | Type | Allowed values | Description |
| --------------- | ------- | ------------------------------------- | ----------- |
| `projectId` | string | | |
| `detachedTasks` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "delete_project",
"arguments": {
"projectId": "244210e4-8437-4655-8980-a70249a99369"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: project deleted. 3 task(s) kept, without a project."
}
],
"structuredContent": {
"projectId": "244210e4-8437-4655-8980-a70249a99369",
"detachedTasks": 3
}
}
}
```
```bash CLI theme={null}
doers projects delete 244210e4-8437-4655-8980-a70249a99369
```
## update\_project
**Update a project.**
Partial patch: name, area, deadline, status or notes. Passing `status: "done"` marks the project complete without touching its tasks.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Write · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `PATCH https://api.doers.sh/v2/projects/{projectId}` |
| CLI | `doers projects update` |
| Touches | `projects`, `tasks` |
| Operation | `updateProject` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------------ | -------------- | -------- | ------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` (path) | string | yes | | UUID | Identifier of a row. |
| `name` | string | no | | 1 to 200 characters | *No description in the registry.* |
| `areaId` | string \| null | no | | UUID | *No description in the registry.* |
| `deadline` | string \| null | no | | `YYYY-MM-DD` | *No description in the registry.* |
| `status` | string | no | | `active`, `done` | *No description in the registry.* |
| `notes` | string | no | | 0 to 10000 characters | Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (\`\`\`) or images**: the app's editor does not support them and truncates the display from that point on. |
| `order` | number | no | | | Manual position. Fractional values are valid; lower sorts first. |
### Output
| Field | Type | Allowed values | Description |
| -------------------- | ----------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `project` | object | | |
| `project.id` | string | | |
| `project.name` | string | | |
| `project.areaId` | string \| null | | |
| `project.status` | string | `active`, `done`, `archived` | |
| `project.deadline` | string \| null | | |
| `project.notes` | string | | |
| `project.order` | number | | Manual position. Fractional values are valid; lower sorts first. |
| `project.accessRole` | string (optional) | `owner`, `editor`, `commenter`, `reader` | Your effective role on this project. |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_project",
"arguments": {
"projectId": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: project “Acme” updated."
}
],
"structuredContent": {
"project": {
"id": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"status": "active",
"deadline": "2026-09-22",
"notes": "Notes for the Acme launch.",
"order": 0,
"accessRole": "owner"
}
}
}
}
```
```bash CLI theme={null}
doers projects update 244210e4-8437-4655-8980-a70249a99369 --name Acme --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf
```