feat(cli): add Linear documents CRUD support

Add documents entity support in linear-core and CLI command registration, including gateway mappers, sdk type aliases, help/docs updates, and tests.

Author: dubscode

README.md

@@ -56,6 +56,7 @@ linear issues list --limit 10
 linear issues browse
 linear issues create --input '{"title":"Investigate bug","teamId":"<team-id>"}'
 linear projects list
+linear documents list
 
 # TUI
 linear tui --screen issues

packages/cli/src/help/root-help.ts

@@ -10,6 +10,7 @@ Examples:
   linear issues browse
   linear issues create --template "Bug Report" --input '{"teamId":"<team-id>"}'
   linear initiatives list
+  linear documents list
   linear templates list
   linear skills install issue-triage
   linear docs --open

packages/cli/src/index.ts

@@ -8,6 +8,8 @@ import type {
   SdkCommentUpdateInput,
   SdkCycleInput,
   SdkCycleUpdateInput,
+  SdkDocumentInput,
+  SdkDocumentUpdateInput,
   SdkInitiativeInput,
   SdkInitiativeUpdateInput,
   SdkIssueInput,
@@ -107,6 +109,14 @@ function isProjectUpdateInput(value: unknown): value is SdkProjectUpdateInput {
   return isRecord(value) && Object.keys(value).length > 0;
 }
 
+function isDocumentCreateInput(value: unknown): value is SdkDocumentInput {
+  return isRecord(value) && hasString(value, "title");
+}
+
+function isDocumentUpdateInput(value: unknown): value is SdkDocumentUpdateInput {
+  return isRecord(value) && Object.keys(value).length > 0;
+}
+
 function isCycleCreateInput(value: unknown): value is SdkCycleInput {
   return isRecord(value) && hasString(value, "teamId");
 }
@@ -561,6 +571,37 @@ export function createProgram(authManager = new AuthManager()): Command {
     authManager,
   );
 
+  registerResourceCommand(
+    program,
+    "documents",
+    "Document commands",
+    {
+      list: async (_manager, cmd) => {
+        const globals = getGlobalOptions(cmd);
+        return (await sessionGateway(cmd)).listDocuments({
+          limit: globals.limit,
+          cursor: globals.cursor,
+        });
+      },
+      get: async (_manager, id, cmd) => (await sessionGateway(cmd)).getDocument(id),
+      create: async (_manager, payload, cmd) =>
+        (await sessionGateway(cmd)).createDocument(
+          ensurePayload(payload, isDocumentCreateInput, "Document create payload requires title."),
+        ),
+      update: async (_manager, id, payload, cmd) =>
+        (await sessionGateway(cmd)).updateDocument(
+          id,
+          ensurePayload(
+            payload,
+            isDocumentUpdateInput,
+            "Document update payload must be a non-empty object.",
+          ),
+        ),
+      delete: async (_manager, id, cmd) => (await sessionGateway(cmd)).deleteDocument(id),
+    },
+    authManager,
+  );
+
   registerResourceCommand(
     program,
     "cycles",
@@ -809,9 +850,7 @@ export function createProgram(authManager = new AuthManager()): Command {
       try {
         const session = await authManager.openSession({ profile: globals.profile });
         const defaultScreen =
-          opts.screen === "projects" ||
-          opts.screen === "initiatives" ||
-          opts.screen === "cycles"
+          opts.screen === "projects" || opts.screen === "initiatives" || opts.screen === "cycles"
             ? opts.screen
             : "issues";
         await runLinearTui({

packages/cli/tests/help.test.ts

@@ -9,6 +9,8 @@ describe("help output", () => {
       program.commands.find((command) => command.name() === "issues")?.helpInformation() ?? "";
     const initiativesHelp =
       program.commands.find((command) => command.name() === "initiatives")?.helpInformation() ?? "";
+    const documentsHelp =
+      program.commands.find((command) => command.name() === "documents")?.helpInformation() ?? "";
     const templatesHelp =
       program.commands.find((command) => command.name() === "templates")?.helpInformation() ?? "";
 
@@ -17,9 +19,11 @@ describe("help output", () => {
     expect(help).toContain("skills");
     expect(help).toContain("issues");
     expect(help).toContain("initiatives");
+    expect(help).toContain("documents");
     expect(help).toContain("templates");
     expect(issuesHelp).toContain("browse");
     expect(initiativesHelp).toContain("create");
+    expect(documentsHelp).toContain("list");
     expect(templatesHelp).toContain("list");
   });
 });

packages/linear-core/src/entities/linear-gateway.ts

@@ -4,6 +4,7 @@ import type {
   AttachmentRecord,
   CommentRecord,
   CycleRecord,
+  DocumentRecord,
   InitiativeRecord,
   IssueRecord,
   LabelRecord,
@@ -22,6 +23,9 @@ import type {
   SdkCycleInput,
   SdkCycleLike,
   SdkCycleUpdateInput,
+  SdkDocumentInput,
+  SdkDocumentLike,
+  SdkDocumentUpdateInput,
   SdkInitiativeInput,
   SdkInitiativeLike,
   SdkInitiativeUpdateInput,
@@ -98,6 +102,19 @@ function toProject(record: SdkProjectLike): ProjectRecord {
   };
 }
 
+function toDocument(record: SdkDocumentLike): DocumentRecord {
+  return {
+    id: record.id,
+    title: record.title,
+    content: record.content ?? undefined,
+    url: record.url,
+    projectId: record.projectId,
+    initiativeId: record.initiativeId,
+    createdAt: toDateString(record.createdAt),
+    updatedAt: toDateString(record.updatedAt),
+  };
+}
+
 function toCycle(record: SdkCycleLike): CycleRecord {
   return {
     id: record.id,
@@ -317,6 +334,38 @@ export class LinearGateway {
     };
   }
 
+  public async listDocuments(options: ListOptions): Promise<PageResult<DocumentRecord>> {
+    const connection = await this.client.documents(toListVariables(options));
+    return {
+      items: connection.nodes.map(toDocument),
+      nextCursor: connection.pageInfo.endCursor ?? null,
+    };
+  }
+
+  public async getDocument(id: string): Promise<DocumentRecord> {
+    return toDocument(await this.client.document(id));
+  }
+
+  public async createDocument(input: SdkDocumentInput): Promise<DocumentRecord> {
+    const payload = await this.client.createDocument(input);
+    return toDocument(await requireEntity(payload.document, "document"));
+  }
+
+  public async updateDocument(id: string, input: SdkDocumentUpdateInput): Promise<DocumentRecord> {
+    const payload = await this.client.updateDocument(id, input);
+    return toDocument(await requireEntity(payload.document, "document"));
+  }
+
+  public async deleteDocument(
+    id: string,
+  ): Promise<{ readonly id?: string; readonly success: boolean }> {
+    const payload = await this.client.deleteDocument(id);
+    return {
+      id: payload.entityId,
+      success: payload.success,
+    };
+  }
+
   public async listCycles(options: ListOptions): Promise<PageResult<CycleRecord>> {
     const connection = await this.client.cycles(toListVariables(options));
     return {

packages/linear-core/src/entities/models.ts

@@ -21,6 +21,17 @@ export interface ProjectRecord {
   readonly updatedAt: string;
 }
 
+export interface DocumentRecord {
+  readonly id: string;
+  readonly title: string;
+  readonly content?: string;
+  readonly url: string;
+  readonly projectId?: string;
+  readonly initiativeId?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
 export interface InitiativeRecord {
   readonly id: string;
   readonly name: string;

packages/linear-core/src/entities/sdk-types.ts

@@ -17,6 +17,11 @@ export type SdkLinearClient = Pick<
   | "createProject"
   | "updateProject"
   | "deleteProject"
+  | "documents"
+  | "document"
+  | "createDocument"
+  | "updateDocument"
+  | "deleteDocument"
   | "cycles"
   | "cycle"
   | "createCycle"
@@ -58,6 +63,7 @@ export type SdkLinearClient = Pick<
 export type SdkIssueLike = Awaited<ReturnType<LinearClient["issue"]>>;
 export type SdkInitiativeLike = Awaited<ReturnType<LinearClient["initiative"]>>;
 export type SdkProjectLike = Awaited<ReturnType<LinearClient["project"]>>;
+export type SdkDocumentLike = Awaited<ReturnType<LinearClient["document"]>>;
 export type SdkCycleLike = Awaited<ReturnType<LinearClient["cycle"]>>;
 export type SdkTeamLike = Awaited<ReturnType<LinearClient["team"]>>;
 export type SdkUserLike = Awaited<ReturnType<LinearClient["user"]>>;
@@ -70,6 +76,7 @@ export type SdkTemplateLike = Awaited<ReturnType<LinearClient["template"]>>;
 export type SdkIssueConnectionLike = Awaited<ReturnType<LinearClient["issues"]>>;
 export type SdkInitiativeConnectionLike = Awaited<ReturnType<LinearClient["initiatives"]>>;
 export type SdkProjectConnectionLike = Awaited<ReturnType<LinearClient["projects"]>>;
+export type SdkDocumentConnectionLike = Awaited<ReturnType<LinearClient["documents"]>>;
 export type SdkCycleConnectionLike = Awaited<ReturnType<LinearClient["cycles"]>>;
 export type SdkTeamConnectionLike = Awaited<ReturnType<LinearClient["teams"]>>;
 export type SdkUserConnectionLike = Awaited<ReturnType<LinearClient["users"]>>;
@@ -82,6 +89,7 @@ export type SdkTemplateListLike = Awaited<LinearClient["templates"]>;
 export type SdkIssuePayloadLike = Awaited<ReturnType<LinearClient["createIssue"]>>;
 export type SdkInitiativePayloadLike = Awaited<ReturnType<LinearClient["createInitiative"]>>;
 export type SdkProjectPayloadLike = Awaited<ReturnType<LinearClient["createProject"]>>;
+export type SdkDocumentPayloadLike = Awaited<ReturnType<LinearClient["createDocument"]>>;
 export type SdkCyclePayloadLike = Awaited<ReturnType<LinearClient["createCycle"]>>;
 export type SdkTeamPayloadLike = Awaited<ReturnType<LinearClient["createTeam"]>>;
 export type SdkUserPayloadLike = Awaited<ReturnType<LinearClient["updateUser"]>>;
@@ -97,6 +105,8 @@ export type SdkInitiativeInput = Parameters<LinearClient["createInitiative"]>[0]
 export type SdkInitiativeUpdateInput = Parameters<LinearClient["updateInitiative"]>[1];
 export type SdkProjectInput = Parameters<LinearClient["createProject"]>[0];
 export type SdkProjectUpdateInput = Parameters<LinearClient["updateProject"]>[1];
+export type SdkDocumentInput = Parameters<LinearClient["createDocument"]>[0];
+export type SdkDocumentUpdateInput = Parameters<LinearClient["updateDocument"]>[1];
 export type SdkCycleInput = Parameters<LinearClient["createCycle"]>[0];
 export type SdkCycleUpdateInput = Parameters<LinearClient["updateCycle"]>[1];
 export type SdkTeamInput = Parameters<LinearClient["createTeam"]>[0];

packages/linear-core/src/types/public.ts

@@ -3,6 +3,7 @@ export type LinearEntity =
   | "issues"
   | "initiatives"
   | "projects"
+  | "documents"
   | "cycles"
   | "teams"
   | "users"

packages/linear-core/tests/linear-gateway.test.ts

@@ -58,6 +58,37 @@ function createTestClient(): SdkLinearClient {
     async deleteProject() {
       throw createNotImplementedError("deleteProject");
     },
+    async documents() {
+      return {
+        nodes: [
+          {
+            id: "doc_1",
+            title: "Agent rollout plan",
+            content: "## Scope",
+            url: "https://linear.app/docs/agent-rollout-plan",
+            projectId: "proj_1",
+            initiativeId: "init_1",
+            createdAt: new Date("2026-03-15T00:00:00.000Z"),
+            updatedAt: new Date("2026-03-16T00:00:00.000Z"),
+          },
+        ],
+        pageInfo: {
+          endCursor: "document-cursor-2",
+        },
+      };
+    },
+    async document() {
+      throw createNotImplementedError("document");
+    },
+    async createDocument() {
+      throw createNotImplementedError("createDocument");
+    },
+    async updateDocument() {
+      throw createNotImplementedError("updateDocument");
+    },
+    async deleteDocument() {
+      throw createNotImplementedError("deleteDocument");
+    },
     async cycles() {
       throw createNotImplementedError("cycles");
     },
@@ -241,6 +272,17 @@ describe("LinearGateway", () => {
     expect(result.nextCursor).toBe("initiative-cursor-2");
   });
 
+  test("lists documents and maps fields", async () => {
+    const gateway = new LinearGateway(createTestClient());
+    const result = await gateway.listDocuments({ limit: 10 });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]?.title).toBe("Agent rollout plan");
+    expect(result.items[0]?.projectId).toBe("proj_1");
+    expect(result.items[0]?.initiativeId).toBe("init_1");
+    expect(result.nextCursor).toBe("document-cursor-2");
+  });
+
   test("lists templates and maps fields", async () => {
     const gateway = new LinearGateway(createTestClient());
     const result = await gateway.listTemplates();