feat(project): add description to create, update, and view by lmjabreu · Pull Request #395 · Doist/todoist-cli

lmjabreu · 2026-06-10T19:25:19Z

What

Surfaces project descriptions (26Q2 Project Essentials) in the CLI. The backend shipped project.description via sync and REST; this wires it into the td project verbs.

td project create and td project update accept --description <text> and --stdin
td project view renders the description as a markdown block below the metadata (--raw to disable rendering)
Curated --json output now includes description

Design notes

Mirrors the task-description surface (--description / --stdin, the CONFLICTING_OPTIONS guard, the Description: view block, markdown rendering) so the two read and behave the same. No client-side length check, consistent with tasks; the backend validates and trims.
Clearing follows the task pattern: pipe empty input via --stdin (sends '', which the backend treats as clear). --description "" is a no-op, matching tasks. No --no-description flag.
SDK gap: the SDK's AddProjectArgs / UpdateProjectArgs don't yet type description, though the REST client forwards it. The args are built as a variable to attach the field without a cast, with a TODO to drop the workaround once a follow-up SDK bump types it. Project reads already carry description in the SDK schema.

Scope

In scope: project descriptions in create / update / view / JSON.
Non-goals: section descriptions (need an SDK update first, the read schema currently strips them) and the MCP. Those are separate follow-up PRs.

Testing

New unit tests for create (--description, --stdin, conflict), update (--description, clear via empty --stdin, conflict), and view (renders block, omits when empty).
Full suite green (1702 tests), type-check, lint/format, and build all pass.
Smoke-tested the built binary with --dry-run.

🤖 Generated with Claude Code

lmjabreu · 2026-06-10T20:51:51Z

@doistbot /review

doistbot

This PR wires up project descriptions across the create, update, and view commands, keeping the new surface perfectly consistent with tasks.

Few things worth tightening:

Retain the SDK parameter types in the addProject workaround so we don't lose compile-time validation for the rest of the payload.
Strengthen the test coverage by using a markdown fixture to concretely test the --raw view behavior, and add an assertion for the new description field in the JSON outputs.

I also included a few optional follow-up notes in the details below.

Optional follow-up note (1)

[P3] src/commands/project/index.ts:115: This PR adds new project command surface (view --raw, create --description/--stdin, update --description/--stdin), but the skill reference wasn't updated alongside it. That leaves src/lib/skills/content.ts and the generated skills/todoist-cli/SKILL.md out of sync with the actual CLI behavior, so agents using td skill install won't discover these new flags.

_{Share Feedback • Review Logs}

lmjabreu · 2026-06-10T21:15:21Z

@doistbot /review

doistbot

This cleanly wires up project descriptions across the create, update, and view commands, nicely matching the established patterns for tasks.

Few things worth tightening:

Update SKILL_CONTENT in src/lib/skills/content.ts to document the new --description, --stdin, and --raw flags for AI agent discovery.
Pass the --raw flag down to the underlying task rows in project view so they don't unintentionally render markdown.
Strengthen a couple of test cases by asserting on a markdown mock sentinel value, and adding a regression check ensuring --description "" remains a no-op on updates.

_{Share Feedback • Review Logs}

lmjabreu · 2026-06-10T21:33:11Z

@doistbot /review

doistbot

This PR nicely wires up project descriptions across the create, update, and view commands, maintaining a consistent experience with existing task patterns.

Few things worth tightening:

Keep the shared JSON projection slim by isolating the description addition to the create, update, and view outputs, as adding it to PROJECT_ESSENTIAL_FIELDS introduces unnecessary serialization overhead to project list paths.
Add a test case for project view --raw with markdown task content (and ideally --detailed) to prove the newly plumbed raw flag correctly prevents rendering in the task-row output.

I also included a few optional follow-up notes in the details below.

Optional follow-up note (1)

[P3] src/lib/skills/content.ts:165: The skill reference still only shows --stdin on project create. Since project update now supports --stdin too (including the empty-stdin clear flow), agents reading SKILL_CONTENT won't discover that path. Add an update example here and regenerate SKILL.md so the reference matches the CLI surface.

_{Share Feedback • Review Logs}

Surface project descriptions (26Q2 Project Essentials) in the CLI: - `project create` / `update` accept `--description <text>` and `--stdin` - `project view` renders the description as a markdown block (`--raw` disables) - curated `--json` output now includes `description` Mirrors the existing task-description flag surface. Clearing follows the same pattern as tasks: pipe empty input via `--stdin`. The SDK's project write-arg types don't yet include `description`, so the args are built as a variable to attach it without a cast; the REST client forwards the field. A follow-up SDK bump can type it and drop the workaround. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Keep the SDK arg signature in `addProject`/`updateProject` via `Parameters<typeof api.x>[...] & { description?: string }`, so only `description` escapes the types and the rest of the payload stays checked. - Make the `--raw` view test meaningful: mock `renderMarkdown` (identity) and assert the description routes through the renderer by default and bypasses it under `--raw` (the renderer is a near no-op in the non-TTY test env, so the prior plain-text assertion couldn't distinguish the two). - Add JSON regression guards asserting `description` survives the curated projection in project create/update/view `--json`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Pass `--raw` through to task rows in `project view` so task content isn't markdown-rendered when the user asked for raw output. - Document the new `--description`, `--stdin`, and `--raw` flags in SKILL_CONTENT (per AGENTS.md) and regenerate SKILL.md. - Strengthen the render test with a sentinel so it proves the renderer's output is what gets logged, not the raw markdown. - Add a regression test that `--description ""` is a no-op on update (clearing is via `--stdin`), guarding the truthiness contract. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…asts SDK 10.4.0 ships `description` on AddProjectArgs and UpdateProjectArgs (via Doist/todoist-sdk-typescript#620), so the temporary type workarounds in project create/update can go. Removed both casts; the SDK signature now covers the full payload. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

doistbot

This diff successfully wires up project descriptions across the CLI creation, update, and view commands, aligning nicely with existing task behaviors.

Few things worth tightening:

Keep the shared JSON projection slim by removing description from PROJECT_ESSENTIAL_FIELDS and mapping it only in the command-specific outputs (create, update, view) to prevent unnecessary overhead on list-heavy paths.
Add a task-list test case to project view --raw with markdown task content to prove the flag correctly leaves task rows unrendered.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (2)

[P3] src/lib/skills/content.ts:165: The skill reference only shows --stdin for project create. Now that project update also supports --stdin (including the flow to clear descriptions with empty input), add an update example here and regenerate SKILL.md so AI agents can discover the new path.
[P3] src/lib/skills/content.ts:160: This --raw example is now inaccurate. The command help says --raw disables markdown rendering, and the implementation also passes raw through task-row rendering, but this comment narrows it to the project description only. Please update the wording so SKILL_CONTENT stays consistent with the actual CLI behavior.

_{Share Feedback • Review Logs}

Address review thread: the existing --raw tests only covered the description block. Add task-list cases that put markdown in task content and assert `--raw` bypasses the renderer for task rows (and that the default path renders them), covering the `raw` passthrough to formatTaskRow(). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

lmjabreu · 2026-06-11T22:56:06Z

Unassigning the review for now: the squad is holding the CLI and MCP description PRs until the feature releases (~next week). The code stays maintained in the meantime; I'll re-request when the hold lifts.

lmjabreu · 2026-06-12T10:31:15Z

Unassigning the review for now: the squad is holding the CLI and MCP description PRs until the feature releases (~next week).

The squad decided to proceed (thread). Rebasing onto main after #396's merge, then re-requesting review.

doistbot reviewed Jun 10, 2026

View reviewed changes

Comment thread src/commands/project/create.ts Outdated

Comment thread src/commands/project/project.test.ts Outdated

Comment thread src/lib/output.ts

doistbot reviewed Jun 10, 2026

View reviewed changes

Comment thread src/commands/project/index.ts

Comment thread src/commands/project/view.ts

Comment thread src/commands/project/project.test.ts

Comment thread src/commands/project/update.test.ts

doistbot reviewed Jun 10, 2026

View reviewed changes

Comment thread src/lib/output.ts

Comment thread src/commands/project/project.test.ts

lmjabreu mentioned this pull request Jun 10, 2026

feat(sections,projects): model description on read and write types Doist/todoist-sdk-typescript#620

Merged

lmjabreu and others added 4 commits June 11, 2026 11:58

lmjabreu force-pushed the lmjabreu/project-descriptions-cli branch from 1e7e70e to 9ca611f Compare June 11, 2026 11:01

lmjabreu marked this pull request as ready for review June 11, 2026 11:01

doistbot requested a review from nvignola June 11, 2026 11:01

doistbot reviewed Jun 11, 2026

View reviewed changes

Comment thread src/lib/output.ts

Comment thread src/commands/project/project.test.ts

lmjabreu removed the request for review from nvignola June 11, 2026 22:56

Merge branch 'main' into lmjabreu/project-descriptions-cli

cfcb9aa

lmjabreu requested a review from nvignola June 12, 2026 10:50

Conversation

lmjabreu commented Jun 10, 2026

What

Design notes

Scope

Testing

Uh oh!

lmjabreu commented Jun 10, 2026

Uh oh!

doistbot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmjabreu commented Jun 10, 2026

Uh oh!

doistbot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmjabreu commented Jun 10, 2026

Uh oh!

doistbot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

doistbot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lmjabreu commented Jun 11, 2026

Uh oh!

lmjabreu commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants