---
title: "comment.add: Add a comment — Note kit command — Kition"
description: "Starts a comment thread anchored to a text range (`from`/`to`), the `occurrence`-th match of `quote`, a heading, or the whole note without an anchor, and answers the thread's and the comment's ids. Comments are kept beside the note, never written into the file."
canonical: "https://developer.kition.ai/docs/kits/note/commands/comment.add"
---

> Canonical HTML: [https://developer.kition.ai/docs/kits/note/commands/comment.add](https://developer.kition.ai/docs/kits/note/commands/comment.add)

# comment.add

**Add a comment.** Starts a comment thread anchored to a text range (`from`/`to`), the `occurrence`-th match of `quote`, a heading, or the whole note without an anchor, and answers the thread's and the comment's ids. Comments are kept beside the note, never written into the file.

- Kit: Note 0.3.0 (Markdown (.md)); reference: [Note kit commands](https://developer.kition.ai/docs/kits/note.md)
- Changes the document: yes

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `author` | `string` | no | The caller's own principal id (the default); the editor's person passes theirs, and another is refused. |
| `body` | `string` | yes | The comment's text. |
| `created` | `string` | no | When, ISO 8601 UTC; now by default. |
| `from` | `integer` | no | Where the commented range starts. |
| `heading` | `string[]` | no | Or a heading's path: comments on the heading. |
| `line` | `integer` | no | Or the heading's line, from 1. |
| `name` | `string` | no | The author's display name. |
| `occurrence` | `integer` | no | Which occurrence of quote, from 1. |
| `quote` | `string` | no | Or the text to comment on; its first occurrence unless occurrence is given. |
| `to` | `integer` | no | Where it ends (exclusive). |
| `unit` | `"scalar" \| "utf16"` | no | How positions are counted: Unicode characters (scalar, the default), or UTF-16 code units as the editor counts them. |

## Call through note_run

```text
note_run {
  "path": "<file>.md",
  "steps": [{ "command": "comment.add", "params": { "body": <string> } }]
}
```

The required parameters, with placeholders for their types: not a tested example. Optional: `author`, `created`, `from`, `heading`, `line`, `name`, `occurrence`, `quote`, `to`, `unit`. note_run answers the step’s result in `completed[i].result`.

## Result

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | `string` | yes | The new comment's id. |
| `thread` | `string` | yes | The thread's id. |

```json
{
  "additionalProperties": false,
  "properties": {
    "comment": {
      "description": "The new comment's id.",
      "type": "string"
    },
    "thread": {
      "description": "The thread's id.",
      "type": "string"
    }
  },
  "required": [
    "comment",
    "thread"
  ],
  "type": "object"
}
```

## Parameter schema

```json
{
  "additionalProperties": false,
  "properties": {
    "author": {
      "description": "The caller's own principal id (the default); the editor's person passes theirs, and another is refused.",
      "type": "string"
    },
    "body": {
      "description": "The comment's text.",
      "type": "string"
    },
    "created": {
      "description": "When, ISO 8601 UTC; now by default.",
      "type": "string"
    },
    "from": {
      "description": "Where the commented range starts.",
      "type": "integer"
    },
    "heading": {
      "description": "Or a heading's path: comments on the heading.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "line": {
      "description": "Or the heading's line, from 1.",
      "type": "integer"
    },
    "name": {
      "description": "The author's display name.",
      "type": "string"
    },
    "occurrence": {
      "description": "Which occurrence of quote, from 1.",
      "type": "integer"
    },
    "quote": {
      "description": "Or the text to comment on; its first occurrence unless occurrence is given.",
      "type": "string"
    },
    "to": {
      "description": "Where it ends (exclusive).",
      "type": "integer"
    },
    "unit": {
      "default": "scalar",
      "description": "How positions are counted: Unicode characters (scalar, the default), or UTF-16 code units as the editor counts them.",
      "enum": [
        "scalar",
        "utf16"
      ],
      "type": "string"
    }
  },
  "required": [
    "body"
  ],
  "type": "object"
}
```

Generated from kition-sdk packages/script/kits/note.ts and the kit itself (kition-note@69e14d9).
